Squad product: Expand team review to include doc coverage and CI improvements

[diberry]

Scope: This is a Squad product issue about improving the team review process. The current Flight/FIDO review cycle checks architecture and test coverage but misses documentation gaps and CI improvements that should accompany every feature or bug fix.

Problem

When Squad agents (Flight + FIDO) review an issue or PR, they currently check:

• Architecture soundness (Flight)
• Code quality and test coverage (FIDO)

But they do NOT check:

• Documentation coverage -- does the feature/fix have corresponding docs? Are existing docs outdated by the change?
• CI improvements -- does this change need new CI checks, workflow updates, or guard modifications?

This means reviewed and "approved" work ships without docs or CI updates, creating debt that accumulates silently.

Examples from this session

1. Squad product: Default workflows burn too many Actions minutes for multi-repo customers #98 (Minutes optimization PRD) -- comprehensive PRD with 5 implementation phases, but no reviewer asked: "Which docs pages need updating? Does the troubleshooting guide cover this? Should squad init print a minutes warning?"

2. Bug: squad-main-guard.yml blocks .squad/ commits on main for solo developers #99 (Main-guard bug) -- bug report about a workflow contradicting Scribe behavior, but no reviewer asked: "Is this documented in the troubleshooting guide? Does the getting-started guide warn solo devs about this?"

3. feat(sdk): StorageProvider abstraction — complete migration + example providers bradygaster/squad#640 (StorageProvider PR) -- 100-file PR adding a major SDK abstraction, but no reviewer asked: "Where are the API docs? Is there a migration guide for existing consumers?"

Proposed: Expand review checklist

Documentation coverage check (new)

Every review should ask:

• Does this change affect any existing docs page?
• Does this feature need a new docs page (feature page, concept page, or API reference)?
• Is the troubleshooting guide updated if this fixes a user-reported bug?
• Does squad init output or squad --help need updating?
• Are there inline code comments that need updating?

CI improvement check (new)

Every review should ask:

• Does this change need a new CI check or modify an existing one?
• Does this change affect a workflow that's in the upgrade manifest (overwriteOnUpgrade)?
• Should a new test be added to the CI pipeline for this behavior?
• Does this change interact with the config-driven CI tier system (Squad product: Default workflows burn too many Actions minutes for multi-repo customers #98)?
• Are there guard workflows that need modification (Bug: squad-main-guard.yml blocks .squad/ commits on main for solo developers #99)?

Implementation options

Option A: Expand Flight and FIDO charters

Add documentation and CI sections to their existing charters. Flight checks docs, FIDO checks CI.

Option B: Add a new team member (PAO or similar)

Add a dedicated reviewer for docs/CI coverage. This keeps Flight and FIDO focused on their core domains.

Option C: Add review ceremony checklist

Add a post-review ceremony that runs a checklist across all domains. The ceremony template includes docs and CI questions.

Option D: Skill-based approach

Create a review skill (.squad/skills/review-completeness/SKILL.md) that any reviewer reads before posting their verdict. The skill contains the expanded checklist.

Recommendation

Option D (skill-based) + Option A (charter update) -- create the skill first so it's immediately usable, then update Flight and FIDO charters to reference it. This gives us the checklist now without waiting for charter changes to be tested.

Acceptance criteria

• Review skill exists with docs + CI checklist
• Flight's charter references the skill for architecture reviews
• FIDO's charter references the skill for quality reviews
• At least one review cycle demonstrates the expanded checklist (before/after comparison)

Related

• Squad product: Default workflows burn too many Actions minutes for multi-repo customers #98 -- PRD review missed docs coverage question
• Bug: squad-main-guard.yml blocks .squad/ commits on main for solo developers #99 -- Bug review missed troubleshooting guide question
• feat(sdk): StorageProvider abstraction — complete migration + example providers bradygaster/squad#640 -- StorageProvider PR review missed API docs question

[github-actions]

🏗️ Squad Triage — Flight (Lead)

Issue: #100 — Squad product: Expand team review to include doc coverage and CI improvements
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

• Flight (Lead) → label: squad:flight
• Procedures (Prompt Engineer) → label: squad:procedures
• EECOM (Core Dev) → label: squad:eecom
• FIDO (Quality Owner) → label: squad:fido
• PAO (DevRel) → label: squad:pao
• CAPCOM (SDK Expert) → label: squad:capcom
• CONTROL (TypeScript Engineer) → label: squad:control
• Surgeon (Release Manager) → label: squad:surgeon
• Booster (CI/CD Engineer) → label: squad:booster
• GNC (Node.js Runtime) → label: squad:gnc
• Network (Distribution) → label: squad:network
• RETRO (Security) → label: squad:retro
• INCO (CLI UX & Visual Design) → label: squad:inco
• GUIDO (VS Code Extension) → label: squad:guido
• Telemetry (Aspire & Observability) → label: squad:telemetry
• VOX (REPL & Interactive Shell) → label: squad:vox
• DSKY (TUI Engineer) → label: squad:dsky
• Sims (E2E Test Engineer) → label: squad:sims
• Handbook (SDK Usability) → label: squad:handbook
• Ralph (Work Monitor) → label: squad:ralph
• @copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

[github-actions]

📋 Assigned to Flight (Lead)

Issue: #100 — Squad product: Expand team review to include doc coverage and CI improvements

Flight will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
Flight, work on issue #100