fix(docs): address Flight review findings for circuit breaker guide

[diberry]

Context

Flight's post-merge review of PR #647 found issues in the circuit breaker guide that was merged without team review.

Fixes

• Replaced phantom @squad/resilience\ import with pseudocode (package doesn't exist)
• Fixed \squad.json\ → \squad.config.ts\ convention
• Added \successThreshold\ explanation
• Fixed pseudocode catch block that double-recorded failure on open-circuit throw

Review

Previously reviewed by Flight (NEEDS FIXES on these specific items) and FIDO (build/test clean).
Cleaned up from diberry/squad PR #74 (closed — mixed concerns with broken CI guard).

[diberry]

🧪 FIDO — Quality Review

PR: #659 — fix(docs): address Flight review findings for circuit breaker guide
File: docs/src/content/docs/guide/building-resilient-agents.md

Checklist

Check	Result
Only 1 file changed	✅ Pass — 1 file, 10 additions / 5 deletions
No .squad/ or CI guard files	✅ Pass — none present
Internal links have no /docs/ prefix	✅ Pass — no internal links added or modified
Single blank lines only (no doubles)	✅ Pass — spacing is clean throughout
No broken markdown syntax	✅ Pass — blockquote, table, and code blocks all well-formed

Notes

• squad.json → squad.config.ts correction is accurate and consistent with the repo's actual config filename.
• The > **Planned API — example only:** callout clearly flags the pseudocode section — good defensive documentation.
• Expanded successThreshold description adds useful clarity without over-explaining.
• Inline comments in the catch block (// Only actual operation failures reach here...) are a nice touch; help readers avoid a common metric-pollution mistake.

No convention violations found. No blockers.

Verdict: APPROVE

[diberry]

🏗️ Flight — Lead Review

Reviewed against my original findings from the post-merge audit of #647. Checked all four items plus project-rule blockers.

✅ Finding 1 — Phantom @squad/resilience import

Replaced with a // Pseudocode comment block and a prominent > **Planned API — example only:** callout. Readers will not attempt to install a non-existent package. Fixed.

✅ Finding 2 — squad.json → squad.config.ts

Corrected in the Configuration section prose. Consistent with the project's actual config convention. Fixed.

✅ Finding 3 — successThreshold explained

Table cell now reads: "In half-open state, close circuit after this many consecutive successes (confirms system recovery)" — adds the half-open context and the recovery signal rationale. Acceptable in tabular form; no need for separate prose. Fixed.

✅ Finding 4 — Double-recording in catch block

The CIRCUIT_OPEN branch is structurally separated from the error-recording else branch. The inline comment // Only actual operation failures reach here, not open-circuit guards makes the intent explicit. The closing paragraph reinforces: "don't conflate them in error metrics." Fixed.

---

Blocker audit

Rule	Status
No /docs/ prefix on internal links	✅ No links added or modified
Single blank lines only	✅ No double-blank-line violations introduced
Convention consistency	✅ squad.config.ts used consistently throughout

---

Minor observation (non-blocking)

console.log('Request succeeded:', data); was added inside the try block — not in scope from the original findings, but it improves example completeness. No objection.

---

Verdict: APPROVE

All four findings addressed correctly. No blockers triggered. Clear to merge.

— Flight

[Copilot]

Pull request overview

Addresses post-merge review findings in the “Building resilient agents” circuit breaker guide by correcting configuration/documentation details and removing references to non-existent APIs.

Changes:

• Updated configuration guidance to reference squad.config.ts and clarified successThreshold semantics.
• Replaced the phantom @squad/resilience import with clearly-labeled pseudocode and improved error-handling notes to avoid conflating open-circuit guards with operation failures.

[Copilot]

This note says circuit breaker support is currently available through Squad's built-in agent configuration, but there doesn't appear to be any corresponding resilience/circuitBreaker configuration surface in the repo (the only circuit breaker implementation is the rate-limit predictive breaker used by watch). Please either point to the real, current configuration/API that exists today, or rephrase this section to be purely pattern guidance (i.e., the helper API is planned and users must implement their own circuit breaker for custom agents).

[diberry]

Fixed — removed phantom config API claim, clarified circuit breaker is built-in to watch

[Copilot]

The text now says to configure the circuit breaker in squad.config.ts, but the example that follows is JSON (and uses a resilience.circuitBreaker shape that does not appear to be documented/recognized elsewhere). This is likely to confuse readers—either switch the code fence/example to a squad.config.ts TypeScript snippet that matches the SDK config pattern, or change the text to reference the actual JSON-based config file name (if supported).

[diberry]

Fixed — replaced squad.config.ts reference with neutral JSON pattern for clarity

[Copilot]

The updated successThreshold description implies the half-open state can allow multiple consecutive successful requests before closing, but earlier the state machine table says HALF-OPEN "Allow a single probe request". Please align the half-open description with the successThreshold behavior (either update the table text, or adjust the threshold semantics described here).

[diberry]

Fixed — aligned half-open state description with successThreshold behavior

[bradygaster]

@diberry i'll hold this one until you go through the review comments

[diberry]

Closing -- will re-open via fork-first pipeline when fully polished.