Repository navigation
docs: issue truth fixes — PRD mode ingestion, state storage, ralph escape hatch (WS-C) - #1572
Merged
Merged
Conversation
… (WS-C) - Rewrite features/prd-mode.md: ingestion/analysis only, removes 'write a PRD for me' framing - Rewrite scenarios/team-state-storage.md: replace .ai-team/ with .squad/, document local/orphan/two-layer backends and squad init --state-backend, remove outdated worktree/submodule strategies - Update features/state-backends.md with two-layer details, git-notes deprecation note, migration guidance - Document .squad/ralph-instructions.md escape hatch in features/ralph.md Related to #1314 (docs recovery — full template/TEMPLATE_MANIFEST work tracked separately in #1314) Closes #1186 Closes #1194 Supersedes part of #1426 Working as PAO (DevRel) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ✅ | Single commit | 1 commit — clean history |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | No Copilot review threads |
| ❌ | CI passing | 1 check(s) still running |
Files Changed (4 files, +171 −650)
| File | +/− |
|---|---|
docs/src/content/docs/features/prd-mode.md |
+43 −94 |
docs/src/content/docs/features/ralph.md |
+13 −105 |
docs/src/content/docs/features/state-backends.md |
+2 −196 |
docs/src/content/docs/scenarios/team-state-storage.md |
+113 −255 |
Total: +171 −650
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🟢 Impact Analysis — PR #1572Risk tier: 🟢 LOW 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (4 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation corrections aligned to current Squad behavior for PRD-mode (ingestion framing), state backend storage, and Ralph’s --execute escape hatch, addressing #1186, #1194, and docs-only recovery for #1314.
Changes:
- Reframes PRD Mode docs around ingestion/analysis of an existing PRD/spec rather than interactive PRD authoring.
- Rewrites team state storage scenario docs to reflect current
.squad/backends (local/orphan/two-layer) and related workflows. - Updates state-backend + Ralph docs (including documenting
.squad/ralph-instructions.mdbehavior).
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/features/prd-mode.md | Updates PRD Mode guidance to ingestion-oriented usage and expectations. |
| docs/src/content/docs/scenarios/team-state-storage.md | Full rewrite describing current .squad/ state backend options and operational workflows. |
| docs/src/content/docs/features/state-backends.md | Adjusts backend reference details, including migration/deprecation notes and architecture framing. |
| docs/src/content/docs/features/ralph.md | Updates Ralph documentation and adds docs for the .squad/ralph-instructions.md escape hatch. |
Review details
Suppressed comments (2)
docs/src/content/docs/scenarios/team-state-storage.md:98
- This config example should include the default
versionfield written bysquad init(packages/squad-sdk/src/config/init.ts:1040-1043) so it matches the generated.squad/config.json.
// .squad/config.json
{
"stateBackend": "orphan"
}
docs/src/content/docs/scenarios/team-state-storage.md:127
- This config example should include the default
versionfield written bysquad init(packages/squad-sdk/src/config/init.ts:1040-1043) so it matches the generated.squad/config.json.
// .squad/config.json
{
"stateBackend": "two-layer"
}
- Files reviewed: 4/4 changed files
- Comments generated: 5
- Review effort level: Lite
| - All backends implement the same interface — agents don't know or care which backend is active | ||
| - Empty directories are automatically pruned after the last file is deleted (orphan backend) | ||
| - The `external-stub` backend type is an unimplemented placeholder that falls back to `local` (the legacy name `external` is still accepted with a deprecation warning); for real external storage see [External State](./external-state) | ||
| - The `external` backend type exists as a stub for future external storage (see [External State](./external-state)) |
Comment on lines
20
to
24
| ## Prerequisites | ||
|
|
||
| Ralph requires access to GitHub Issues and Pull Requests via the `gh` CLI. **A GitHub PAT (Personal Access Token) with Classic scope is required.** | ||
|
|
||
| ### Why PAT Classic? | ||
|
|
||
| The default `GITHUB_TOKEN` provided by Copilot does not have sufficient scopes to read and write GitHub Issues and PRs. Ralph needs to: | ||
| - List and read issues |
| - When asked "Authenticate Git with your GitHub credentials?", answer "Yes" | ||
| - Choose "Paste an authentication token" and paste your PAT Classic token | ||
|
|
||
| 3. **Verify authentication:** |
| - Read a PRD from a file path you provide | ||
| - Summarize requirements, risks, and open questions | ||
| - Suggest implementation slices, milestones, or issue breakdowns | ||
| There is **no special CLI command or router for PRD mode** in the current implementation. The feature works because you can point Squad at an existing document and ask for analysis. |
Comment on lines
+65
to
+68
| // .squad/config.json | ||
| { | ||
| "stateBackend": "local" | ||
| } |
Collaborator
Author
RETRO Gate Review — WS-C (#1572)Reviewer: RETRO (Security) | Date: 2026-08-02T18:49:04-07:00 | Adjudication refs: pr-1426-gate-adjudication.md, issue-1314-closure-verdict.md Gate Checklist
#1314 Close Keyword — Final RulingThe adjudication document (pr-1426-gate-adjudication.md, Issue 2) originally directed that
Using RETRO ruling: The Copilot Bot Suppressed Comments (Logged)The bot suppressed two comments noting that config examples in team-state-storage.md should include the Verdict✅ APPROVE TO MERGE All RETRO blocking gates pass. Copilot bot reviewed all 4 files substantively. RETRO — Security. Thorough but pragmatic. These gates are real risks, not hypothetical ones. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Issue-specific truth fixes for #1186 and #1194. Docs recovery for #1314. This is WS-C of the four-part #1426 replacement strategy (see design review).
File Scope
docs/src/content/docs/features/prd-mode.mddocs/src/content/docs/scenarios/team-state-storage.md.squad/backends replacing.ai-team/eradocs/src/content/docs/features/state-backends.mddocs/src/content/docs/features/ralph.md.squad/ralph-instructions.mdescape hatchChanges Applied
features/prd-mode.md (Closes #1186)
Write a PRD for a user authentication system)Read the PRD at docs/product-spec.md and summarize…## What it does not do todaysection.squad-templates/prd-intake.mdingestion triggersscenarios/team-state-storage.md (Closes #1194)
.ai-team/throughout (old directory name)squad init --state-backendand.squad/config.jsonconfigurationsquad upgrade --state-backendmigration, inspect/debug commandsfeatures/state-backends.md
features/ralph.md (Related to #1314)
.squad/ralph-instructions.mdescape hatch accuratelyCloses #1314— the issue's Option A also requires a template atpackages/squad-cli/templates/ralph-instructions.mdregistered inTEMPLATE_MANIFEST. This is docs recovery only; template/manifest work remains open in DX:.squad/ralph-instructions.mdis an undocumented escape hatch insquad watch --execute— document it or remove it #1314.FIDO Audit Findings Addressed
Validation
npm run buildindocs/: ✅ passes (0 errors)grep 'write a PRD\|generate a requirements' features/prd-mode.md→ 0 matches ✅grep 'ai-team' scenarios/team-state-storage.md→ 0 matches ✅grep 'ralph-instructions' features/ralph.md→ present ✅Closes #1186
Closes #1194
Related to #1314
Supersedes part of #1426
Working as PAO (DevRel)