docs(problems): add flapping and convergence problem doc

[Benkapner]

Summary

• New problem document addressing non-converging agent behavior: fix-break oscillation, review ping-pong, approach churn, and flaky-test loops
• Explores detection approaches with trade-offs: cycle detection via state hashing, diff-distance damping, cost/turn accounting across retries, and review comment velocity heuristics
• Explores response strategies with trade-offs: circuit breaker with escalation, strategy rotation (connecting to adaptive-agent-selection), cooldown with context injection (connecting to cross-run-memory), and abandon-and-report
• Discusses configurable thresholds per repo and per agent role

Flapping is referenced in three existing docs (autonomy-spectrum, agent-architecture, code-review) but never given dedicated treatment. At fullsend's target scale, flapping becomes an operational problem: cost waste, PR noise, blocking, and credibility loss with human maintainers.

The doc stays at the problem/exploration level. Detection mechanisms and response strategies are described as approaches with trade-offs, not as a prescribed architecture.

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

docs(problems): add flapping and convergence problem doc

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Add a dedicated problem doc defining agent flapping and non-converging behavior patterns.
• Describe detection approaches (state hashing, diff reversal, budget accounting, comment velocity).
• Outline response strategies and configurable thresholds, linking to related problem areas.

Diagram

graph TD
  F["Flapping & Convergence doc"] --> D["Detection"] --> R["Response strategies"] --> T["Threshold config"]
  F --> A["Adaptive selection"] --> M["Cross-run memory"] --> O["Operational observability"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Fold content into existing docs (agent-architecture/code-review/autonomy-spectrum)

• ➕ Reduces doc sprawl; readers find guidance where they already are
• ➕ Avoids maintaining an additional index/entry point
• ➖ Flapping spans multiple areas; content becomes fragmented and harder to reference as a single operational problem
• ➖ Harder to evolve into a consistent policy/budget model later

2. Write as an operational runbook/policy instead of a problem exploration

• ➕ More immediately actionable for operators (explicit budgets, escalation triggers, reporting format)
• ➕ Easier to standardize across repos/roles
• ➖ Premature prescription; may lock in thresholds/metrics before enough experience
• ➖ Less useful as a conceptual taxonomy of failure modes

Recommendation: Keeping a dedicated problem doc is the best choice given the cross-cutting nature (detection + remediation + configuration + observability). Consider a follow-up to add explicit backlinks from the three docs that currently mention flapping so readers can discover this page from those contexts.

Files changed (1) +105 / -0

Documentation (1) +105 / -0

flapping-convergence.mdAdd flapping/non-convergence problem doc with detection and response options +105/-0

Add flapping/non-convergence problem doc with detection and response options

• Introduces a new documentation page defining flapping patterns (fix-break oscillation, review ping-pong, approach churn, flaky-test loops) and why they matter operationally at scale. Describes candidate detection mechanisms and response strategies with trade-offs, and highlights the need for configurable thresholds per repo and agent role.

docs/problems/flapping-convergence.md

[github-actions]

Site preview

Preview: https://1b2799b3-site.fullsend-ai.workers.dev

Commit: 16621d899e17edff74cbbb1c4631594c9836fefd

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Org-specific fullsend mention ✓ Resolved 📘 Rule violation § Compliance

Description

The core problem doc includes organization/product-specific wording (fullsend's target scale),
which violates the requirement that core docs under docs/problems/ remain generic. This content
should be generalized or moved under docs/problems/applied/<org-name>/.

Code

docs/problems/flapping-convergence.md[R30-31]

+A single flapping agent on one repo is annoying. Twenty flapping agents across an organization's repositories are a resource drain. At fullsend's target scale (20+ repos, multiple agent roles per repo), flapping becomes an operational problem:
+

Relevance

⭐⭐⭐ High

Team previously required core problem docs be org-agnostic; org-specific content moved to
docs/problems/applied/ (PR #42, #12).

PR-#42
PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062038 requires core problem docs (outside docs/problems/applied/) to avoid
organization-specific identifiers. The added paragraph explicitly references `fullsend's target
scale`, making the core doc non-generic.

Rule 1062038: Separate generic and organization-specific problem documents
docs/problems/flapping-convergence.md[30-35]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new core problem document includes organization/product-specific identifiers (`fullsend's target scale`), which should not appear in core docs outside `docs/problems/applied/<org-name>/`.

## Issue Context
Core problem docs must be generic. Organization-specific examples, scale assumptions, or internal identifiers must be moved into an applied doc under `docs/problems/applied/<org-name>/`, with the core doc linking to it if needed.

## Fix Focus Areas
- docs/problems/flapping-convergence.md[30-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Broken trustworthiness link 🐞 Bug ≡ Correctness

Description

docs/problems/flapping-convergence.md links to trustworthiness-evidence.md, but that target file is
not present in the repository, creating a dead cross-reference in the docs. This is easy to miss
because the docs site config explicitly ignores dead links during build.

Code

docs/problems/flapping-convergence.md[97]

+- **[Trustworthiness Evidence](trustworthiness-evidence.md)** — Flapping rate is a negative trustworthiness signal. An agent that flaps frequently on a repo is less trustworthy than one that converges reliably.

Relevance

⭐⭐⭐ High

Broken/missing markdown doc links are routinely fixed in reviews; multiple accepted suggestions to
remove/repair dead links (PR #2009, #226, #601).

PR-#2009
PR-#226
PR-#601

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new doc contains a markdown link to a non-existent file, and the docs build is configured to
ignore dead links, increasing the chance this broken reference ships unnoticed.

docs/problems/flapping-convergence.md[91-98]
website/.vitepress/config.ts[135-142]
PR-#226

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`docs/problems/flapping-convergence.md` links to `trustworthiness-evidence.md`, but there is no such document in the repo, so the link is broken.

### Issue Context
The docs site is built with VitePress and is configured with `ignoreDeadLinks: true`, so dead links will not fail CI/builds and can silently ship.

### Fix Focus Areas
- docs/problems/flapping-convergence.md[91-98]
- website/.vitepress/config.ts[135-142]

### Recommended fix
Choose one:
1) **Update the link** to an existing page/section (e.g. `../roadmap.md#trustworthiness-evidence` if that’s the intended reference), or
2) **Add the missing doc** at `docs/problems/trustworthiness-evidence.md` (even as a stub) so the cross-reference resolves.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

2. Broken trustworthiness link 🐞 Bug ≡ Correctness

docs/problems/flapping-convergence.md links to trustworthiness-evidence.md, but that target file is
not present in the repository, creating a dead cross-reference in the docs. This is easy to miss
because the docs site config explicitly ignores dead links during build.

Agent Prompt

### Issue description
`docs/problems/flapping-convergence.md` links to `trustworthiness-evidence.md`, but there is no such document in the repo, so the link is broken.

### Issue Context
The docs site is built with VitePress and is configured with `ignoreDeadLinks: true`, so dead links will not fail CI/builds and can silently ship.

### Fix Focus Areas
- docs/problems/flapping-convergence.md[91-98]
- website/.vitepress/config.ts[135-142]

### Recommended fix
Choose one:
1) **Update the link** to an existing page/section (e.g. `../roadmap.md#trustworthiness-evidence` if that’s the intended reference), or
2) **Add the missing doc** at `docs/problems/trustworthiness-evidence.md` (even as a stub) so the cross-reference resolves.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[Benkapner]

this link resolves when PR #3058 (trustworthiness-evidence.md) merges. both PRs are open concurrently. if #3058 merges first the link is valid; if this one merges first i'll remove the link and re-add it when #3058 lands but if code owners says otherwise i can remove the link..

[ralphbean]

LGTM. One non-blocking note inline.

CI is failing on the trustworthiness-evidence.md link, but #3058 is merged now — a rebase on main should fix it.

[ralphbean]

[minor] Three existing docs touch on flapping-adjacent concepts (code-review.md on review iteration, agent-architecture.md on iteration limits, autonomy-spectrum.md on escalation triggers). Might be worth adding a backlink from those docs to this one so readers can discover it from context. Not blocking — could be a follow-up.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 4:31 PM UTC · Completed 4:39 PM UTC
Commit: 16621d8 · View workflow run →

[fullsend-ai-retro]

PR #3064 added a new flapping-convergence problem doc to fullsend-ai/fullsend. The workflow was mostly efficient (3 commits, ~6 hours to merge), with the Qodo bot catching two valid findings (org-specific wording, broken cross-PR link) and the human reviewer (ralphbean) adding backlinks from existing docs. However, both the automated and human reviewers missed that AGENTS.md requires new problem docs to be linked from README.md — flapping-convergence.md is now absent from the curated README index. The Qodo bot also identified the backlinks gap in its summary but did not elevate it to an actionable inline finding, requiring the maintainer to independently identify and implement the fix.

Proposals filed

• Review agent and Qodo should flag missing README.md entry when new problem docs are added (in fullsend-ai/fullsend)
• Add AGENTS.md guidance: new problem docs should include backlinks from existing docs that reference the topic (in fullsend-ai/fullsend)
• Qodo review should elevate cross-reference gap findings from summary to inline comments (in fullsend-ai/fullsend)