ezos26/claude-skills/ralph-planning-audit

For each story, verify:
- Has id, title, priority, status, description
- Has acceptance_criteria (non-empty array)
- Has files_to_modify or files_to_create (at least one non-empty)
- depends_on references only valid story IDs
- No circular dependencies
- Priority numbers are unique (warn if not)

- Build adjacency list from depends_on
- Topological sort — if cycle detected, report immediately
- Identify stories with no dependents (leaf nodes) and no dependencies (roots)
- Flag stories whose depends_on includes IDs not in the PRD

- Build map: file_path -> [story IDs that touch it]
- Any file touched by 3+ stories is HIGH risk
- Any file touched by 2 stories that aren't in a dependency chain is MEDIUM risk
- Report the collision map

Phase 1: Quick Validation
=========================
Stories: {count} ({incomplete} incomplete, {complete} complete)
Dependency graph: {VALID / CYCLES: list}
File collisions: {count} ({HIGH_count} high-risk, {MEDIUM_count} medium-risk)
Schema issues: {count or "none"}

## Agent Roster (you are Agent {N})
1. Codebase Reality Agent — verifies files exist, code assumptions are correct
2. Sequencing & Dependency Agent — execution order, missing deps, parallel opportunities
3. Scope & Feasibility Agent — story sizing, acceptance criteria quality, one-context-window fit
4. Contract & Integration Agent — API contract compliance, cross-system effects
5. Gap Analysis Agent — missing stories, uncovered edge cases, incomplete coverage
 
If you find something outside your domain, note it as:
  CROSS-REF [Agent N]: [what they should check]

{context block}
 
{agent roster}
 
## Your Focus: Codebase Reality Check
 
For EVERY story in the PRD:
 
1. **File existence**: Do all `files_to_modify` actually exist? Read each one.
2. **Code assumptions**: Does the story description match what's actually in the file?
   - If a story says "fix line ~332 where customerEmail defaults to empty string" — verify that line exists and says what the story thinks it says.
   - If a story says "add column to schema" — verify the column doesn't already exist.
   - If a story says "update endpoint to accept new param" — verify the endpoint exists and doesn't already accept it.
3. **Import/dependency assumptions**: If a story assumes a module exists or exports something, verify it.
4. **Files NOT in the PRD**: Are there files that obviously need changes but aren't listed in any story? (e.g., if a schema changes, does a migration story exist?)
 
## OUTPUT FORMAT (MANDATORY)
CODEBASE REALITY REPORT
=======================
Stories Verified: {count}
 
Per-Story:
- {STORY_ID}: {PASS / ISSUES}
  {if issues: list each with file:line and what's wrong}
 
Missing from PRD (files that need changes but no story covers them):
- {file}: {why it needs changes}
 
Phantom References (files/lines that don't exist as described):
- {STORY_ID}: {what's wrong}
 
CROSS-REF:
- [Agent N]: [what they should verify]

{context block}
 
{agent roster}
 
## Your Focus: Sequencing & Dependencies
 
1. **Dependency correctness**: For each `depends_on`, verify the dependency is real:
   - Does story B actually need story A's output to work?
   - Or could B run independently?
   - Are there MISSING dependencies? (Story C modifies a file that story A creates, but C doesn't depend on A)
 
2. **Execution order optimization**:
   - Given the dependency graph, what's the critical path?
   - Which stories can run in parallel (same priority, no deps between them)?
   - Are there unnecessary sequential constraints slowing things down?
 
3. **File conflict sequencing**:
   - If stories A and B both modify `worker/src/index.ts`, is there a dependency between them?
   - If not, will they conflict? (Both changing the same function = conflict. Different functions = safe.)
   - Read the actual files to determine if parallel execution of same-file stories is safe.
 
4. **Priority ordering**:
   - Does priority order match dependency order? (A story shouldn't have higher priority than its dependency)
   - Are there priority ties that could cause ambiguity?
 
## OUTPUT FORMAT (MANDATORY)
SEQUENCING REPORT
================
Critical Path: {story IDs in order, with total depth}
Parallelizable Batches:
  Batch 1: [{story IDs}]
  Batch 2: [{story IDs}]
  ...
 
Dependency Issues:
- {STORY_ID}: {MISSING_DEP / UNNECESSARY_DEP / WRONG_ORDER}
  Reason: {explanation}
 
File Conflict Risks:
- {file}: touched by [{story IDs}]
  Safe to parallelize: {YES/NO}
  Reason: {different functions / same function / etc.}
 
Priority Corrections Needed:
- {STORY_ID}: priority {current} should be {suggested} because {reason}
 
CROSS-REF:
- [Agent N]: [what they should verify]

{context block}
 
{agent roster}
 
## Your Focus: Scope & Feasibility
 
For EVERY story:
 
1. **One-context-window fit**: Can this story be completed in a single Claude context window?
   - Count: files to read + files to modify + acceptance criteria complexity
   - If a story touches 5+ files or has 8+ acceptance criteria, it's likely too large
   - Flag stories that should be split
 
2. **Acceptance criteria quality**:
   - Are criteria specific and testable? ("pnpm typecheck passes" = good. "Works correctly" = bad.)
   - Do criteria cover all the changes described?
   - Are there acceptance criteria that contradict each other?
   - Is "pnpm typecheck passes" included? (Required per project conventions)
 
3. **Description sufficiency**:
   - Does the description give enough context for an autonomous agent to implement?
   - Are there ambiguous decisions the agent would need to make?
   - Would the agent need to ask clarifying questions?
 
4. **Risk assessment**:
   - Which stories have the highest risk of breaking something?
   - Which stories are most likely to need human intervention?
   - Flag any story that requires external access (API keys, other repos, manual steps)
 
## OUTPUT FORMAT (MANDATORY)
SCOPE & FEASIBILITY REPORT
==========================
Stories Assessed: {count}
 
Too Large (split recommended):
- {STORY_ID}: {reason} -> suggested split: [{sub-story descriptions}]
 
Weak Acceptance Criteria:
- {STORY_ID}: {what's missing or vague}
 
Ambiguous Descriptions:
- {STORY_ID}: {what decision is left unclear}
 
External Dependencies (may block Ralph):
- {STORY_ID}: requires {what} — {suggestion}
 
Risk Ranking (highest risk first):
1. {STORY_ID}: {risk description}
2. {STORY_ID}: {risk description}
3. ...
 
CROSS-REF:
- [Agent N]: [what they should verify]

{context block}
 
{agent roster}
 
## Your Focus: Contract & Integration Compliance
 
1. **API contract preservation**:
   - Read the API contract doc (frontend-api-contract.md or equivalent)
   - For every story that modifies an API endpoint, verify the change preserves the contract
   - Flag any story that would break the frontend
   - Check: response shapes, status codes, field names (snake_case), error formats
 
2. **Cross-system effects**:
   - If a story changes the DB schema, do all downstream consumers handle the change?
   - If a story changes a Trigger.dev job's payload, does the trigger caller match?
   - If a story changes env vars, is .env.example updated?
 
3. **Backward compatibility**:
   - Are there existing customers/orders that would be affected?
   - Do migration stories handle existing data?
   - Is there a rollback path if something goes wrong?
 
4. **Frontend handoff alignment** (if frontend handoff doc exists):
   - Do the planned changes align with what the frontend team was told?
   - Will any story contradict the frontend handoff doc?
   - Are there backend changes the frontend expects that no story covers?
 
## OUTPUT FORMAT (MANDATORY)
CONTRACT & INTEGRATION REPORT
=============================
API Contract: {PRESERVED / AT RISK}
 
Per-Story Contract Impact:
- {STORY_ID}: {SAFE / RISK: description}
 
Cross-System Effects:
- {STORY_ID}: {effect on other systems}
 
Backward Compatibility:
- {STORY_ID}: {compatible / BREAKING: what breaks}
 
Frontend Handoff Alignment:
- {ALIGNED / GAPS: list what's missing or contradictory}
 
CROSS-REF:
- [Agent N]: [what they should verify]

{context block}
 
{agent roster}
 
## Your Focus: Gap Analysis
 
1. **Read every handoff doc, plan doc, and known-issues section** referenced in the project.
   - Compare against the PRD stories
   - Flag any known issue or planned feature that has NO corresponding story
 
2. **Edge cases not covered**:
   - If a story adds error handling, does it cover all error paths?
   - If a story changes a flow, are rollback/retry scenarios handled?
   - If a story adds a feature, is the feature's removal/deprecation path considered?
 
3. **Testing gaps**:
   - Are there stories for adding tests? (If test coverage is zero and this matters)
   - Do high-risk stories have verification steps beyond typecheck?
 
4. **Documentation gaps**:
   - Will the changes require AGENTS.md updates beyond what's in the PRD?
   - Are there README or setup guide updates needed?
   - Do new env vars need documentation?
 
5. **Operational gaps**:
   - Is there a story for monitoring/alerting on new features?
   - Is there a deployment/migration ordering concern?
   - Are there manual steps between stories that Ralph can't do?