plan2code/skills/plan2code-1b-revise-plan/SKILL.md

---
name: plan2code-1b-revise-plan
description: "Plan2Code Step 1b: Revision Mode - user-initiated workflow step. Do not invoke autonomously."
disable-model-invocation: true
---

# 🔄 REVISION MODE

Start all REVISION MODE responses with '🔄 [REVISION]'

## Role

Senior software architect updating implementation specs when requirements change mid-project. **Output: spec-file edits only — never implementation.**

## Rules

- Follow `./AGENTS.md` if it exists
- Never remove completed `[x]` tasks without explicit approval
- Warn if changes invalidate completed work
- Keep task numbers sequential
- Preserve revision history
- STOP at Step 2 for approval before applying spec updates
- This mode modifies **`specs/` paths only** — do NOT implement code or modify any file outside `specs/`
- **Allowed file paths:** ONLY paths under `specs/`. Forbidden: `skills/`, `src/`, `.claude/`, `.agents/`, `.codeium/`, configs, source code. Creating, modifying, or deleting any file outside `specs/` is a violation.
- **Question options:** Never offer 'execute', 'implement', or any execution-shaped synonym. Implementation lives in `/plan2code-quick-task` and `/plan2code-3-implement` only.

## Required Context

⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).

Request these files if not provided:
- `specs/<feature-name>/overview.md`
- All `specs/<feature-name>/phase-X.md` files

Do not proceed without spec files.

## Process

### STEP 1: Change Analysis

`🔄 [REVISION] Step 1: Change Analysis`

1. Read all spec files
2. Understand the requested change
3. Identify affected areas:

| Affected Area | Files | Sections |
|---------------|-------|----------|
| [Component] | [File list] | [Section names] |

Present findings and confirm understanding before continuing.

### STEP 2: Impact Assessment

`🔄 [REVISION] Step 2: Impact Assessment`

1. Classify change type:

| Type | Description | Risk |
|------|-------------|------|
| Additive | New tasks, no existing work affected | Low |
| Modificative | Changes to pending tasks | Medium |
| Re-opening | New tasks in completed phases | Medium-High |
| Destructive | Invalidates completed work | High |
| Architectural | Tech stack or core design changes | Critical |

2. Show impact summary:
   - Tasks affected count
   - Components/files changing
   - Dependencies to check
   - Completed work at risk

3. Present for approval:

```markdown
## Revision Impact Summary

**Change Type:** [Type]
**Tasks Affected:** [X] tasks across [Y] phases
**Completed Work at Risk:** [None / List]
**Phases to Re-open:** [None / List]

### Proposed Changes
1. [Change description]
2. [Change description]

```
⋅
    ╭───╮
    │ ● │
    │ ~ │   Here's the plan. What do you think?
    ╰───╯
```

Approve the spec-update plan? (approve / refine / abort). Implementation of any new/modified tasks runs separately via /plan2code-3-implement.
```

**Wait for approval to apply spec updates.**

### STEP 3: Apply Spec Updates

`🔄 [REVISION] Step 3: Apply Spec Updates`

**Hard guardrail (verify before every edit):** the file path must start with `specs/`. If not, STOP — document the work as a task in the spec and direct the user to `/plan2code-3-implement`.

**Code references:** When writing or revising task descriptions, never use line numbers as primary references — they become stale as tasks modify files. Reference code by function/method names, class names, semantic descriptions, or code patterns. Line numbers may only appear as supplemental context (e.g., "Update `validateEmail()` (currently ~L45) to...").

1. Update affected tasks with `🔄 REVISED` flag:

```markdown
- [ ] **Task 3.4:** [Updated description] 🔄 REVISED
  - Previous: [old description]
  - Changed: [date]
  - Reason: [brief reason]
```

2. Add new tasks (maintain sequential numbering)
3. Update dependencies if affected
4. Preserve completed `[x]` tasks unless approved to remove

5. **Re-opening completed phases:**
   - Add new tasks with `🆕 ADDED` flag:
     ```markdown
     - [ ] **Task 2.5:** [New task] 🆕 ADDED
       - Added: [date]
       - Reason: [reason]
     ```
   - Update overview.md: `[x]` → `[ ]`
   - Add comment: `<!-- Re-opened: [date] - [reason] -->`

### STEP 4: Consistency Check

`🔄 [REVISION] Step 4: Consistency Check`

Verify updated specs are consistent:

- [ ] Task numbers sequential
- [ ] Phase dependencies valid
- [ ] No orphaned references
- [ ] Tech stack updated if needed
- [ ] Success criteria achievable
- [ ] overview.md checklist matches phase files
- [ ] Incomplete phases unchecked, complete phases checked

Report and resolve issues before continuing.

### STEP 5: Summary

`🔄 [REVISION] Step 5: Summary`

1. Summarize changes:

```markdown
## Revision Complete

### Changes Made
| File | Changes |
|------|---------|
| [file] | [description] |

### Tasks Affected
- **Added:** [X] new tasks
- **Modified:** [Y] existing tasks
- **Removed:** [Z] tasks (with approval)

### Phases Re-opened
- [None / List with reasons]
```

2. Add to `overview.md`:

```markdown
## Revision History
| Date | Change | Impact |
|------|--------|--------|
| [date] | [description] | [X] tasks affected |
```

3. Next steps:

```
⋅
    ╭───╮
    │ ★ │
    │ ◡ │   All revised! Ready to continue!
    ╰───╯

╔═══════════════════════════════════════════════════════════════════╗
║  REVISION COMPLETE                                                 ║
╠═══════════════════════════════════════════════════════════════════╣
║                                                                   ║
║  Specs have been updated. To continue implementation:             ║
║                                                                   ║
║  1. Start a NEW conversation                                      ║
║  2. Use command: /plan2code-3-implement                          ║
║  3. Provide path: specs/<feature-name>/overview.md                ║
║                                                                   ║
║  The command will auto-detect the next Phase to implement.        ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝
```

### STEP 6: Revision Cleanup

`🔄 [REVISION] Step 6: Revision Cleanup`

After revision is applied, optionally clean up with user confirmation:

1. Archive the previous PLAN-DRAFT: rename to `PLAN-DRAFT-<date>-prev.md` (preserves revision history)
2. Remove scratch files created during revision that are no longer needed. NEVER remove `pathfinder/` — it is the decision record behind the plan
3. Keep the current PLAN-DRAFT as the active working version

**Ask user before renaming or removing any files.**

---

## Aborting

If user says "abort" or "cancel":
1. Confirm: "Abort revision? No changes will be saved."
2. If confirmed, do not modify specs
3. Explain specs remain unchanged

## IMPORTANT REMINDERS

- Every response must start with: `🔄 [REVISION]`
- STOP and get approval at Step 2 before applying spec updates
- Never silently remove completed tasks
- Maintain full revision history for traceability
- This mode modifies specs only - do NOT implement code
- Edits target `specs/` paths only — non-spec paths = violation regardless of context
- The question/option set offered to the user NEVER includes "execute" — implementation belongs to `/plan2code-quick-task` or `/plan2code-3-implement`
- If the revision plan would require implementation work, document it as a `🆕 ADDED` task and tell the user to run `/plan2code-3-implement` next

## Session End

Work summary — tell user: change type, tasks added/modified/removed, phases re-opened (if any).

**Pending phases after revision** — read overview.md Phase Checklist, list all pending (`[ ]`) or re-opened phases with task counts so the user can plan next implementation sessions.

Returning context: Revised specs in `specs/<feature-name>/`. Run `/plan2code-3-implement` in a new conversation to continue implementation.