refactor

Refactor Spec

Update specification files after execution. You are a coordinator, not a writer -- delegate actual updates to the refactor-specialist subagent.

Checklist

Create a task for each item and complete in order:

1. Gather context -- resolve spec, read existing files and learnings
2. Determine scope -- which files to refactor (from --file flag or all)
3. File-by-file review -- section-by-section review with user for each file
4. Delegate updates -- dispatch refactor-specialist for each file
5. Handle cascades -- propagate changes downstream if needed
6. Finalize -- update state, commit

Step 1: Gather Context

1. If $ARGUMENTS contains a spec name, use ralph_find_spec() to resolve it; otherwise use ralph_resolve_current()
2. If no active spec, error: "No active spec. Run /ralph-specum:new first."
3. Check the resolved spec directory exists
4. Read .ralph-state.json if exists
5. Identify which spec files exist: requirements.md, design.md, tasks.md
6. If no spec files exist, error: "No spec files found. Run /ralph-specum:start first."
7. Read .progress.md to understand implementation learnings

Step 2: Determine Scope & Present Overview

Check $ARGUMENTS for --file= flag:

• --file=requirements: Only requirements.md
• --file=design: Only design.md
• --file=tasks: Only tasks.md
• No flag: All files in order (requirements -> design -> tasks)

Present overview to user:

Spec: $spec

Files to review:
- requirements.md: [exists/missing] - [brief summary: X user stories, Y requirements]
- design.md: [exists/missing] - [brief summary: X components, Y decisions]
- tasks.md: [exists/missing] - [brief summary: X tasks, Y completed]

Implementation learnings from .progress.md:
- [Key learning 1]
- [Key learning 2]

Prototype Refactor Gate

After resolving the ordered file list above and before any refactor dispatch:

1. Whenever .ralph-state.json exists, reconcile candidates and finals once, even when activePrototypes is absent or empty:

   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/prototype-records.py" reconcile --base-path "$SPEC_PATH" --state "$SPEC_PATH/.ralph-state.json"
   

2. For each resolved file in scope, run selection with that exact file as both target and path:

   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/prototype-records.py" select-downstream --base-path "$SPEC_PATH" --state "$SPEC_PATH/.ralph-state.json" --target "$FILE" --path "$FILE"
   

3. Stop that file's refactor dispatch when activeBlockers targets the file or transition, when its task index appears in staleTaskIndexes, or when staleArtifacts contains the file or an upstream dependency.
4. Preserve a file only when its matching targetDecisions entry has proofAvailable: true and eligible: true. Missing dependency or approved-transfer proof blocks that file conservatively.
5. When refactor resumes execution, restore taskIndex from the relevant entry's returnTaskIndex before task dispatch.