|
| 1 | +--- |
| 2 | +name: spec-kit-reconcile |
| 3 | +description: Use when specification drift is discovered at any stage and existing Spec Kit artifacts (`spec.md`, `plan.md`, `tasks.md`) must be reconciled in-place without creating a new feature branch. |
| 4 | +--- |
| 5 | + |
| 6 | +# Spec Kit Reconcile |
| 7 | + |
| 8 | +Close specification drift by updating existing Spec Kit artifacts in-place. |
| 9 | + |
| 10 | +## When to Use |
| 11 | + |
| 12 | +- You discover specification drift at any stage (specify, clarify, plan, tasks, analyze, or implement) and need artifacts realigned before continuing. |
| 13 | +- Code exists, but behavior still misses expected flows (routing/navigation wiring, integration handoff, validation UX, coverage gaps). |
| 14 | +- `spec-kit-analyze` found issues that require coordinated edits across `spec.md`, `plan.md`, and `tasks.md`. |
| 15 | +- You need targeted remediation planning without creating a new feature branch. |
| 16 | + |
| 17 | +## When Not to Use |
| 18 | + |
| 19 | +- You need a brand-new feature spec (`spec-kit-specify` first). |
| 20 | +- You need first-pass design decomposition from an approved spec (`spec-kit-plan` first). |
| 21 | +- You only need a read-only audit (`spec-kit-analyze`). |
| 22 | +- You are only executing already-correct tasks (`spec-kit-implement`). |
| 23 | + |
| 24 | +## Router Fit |
| 25 | + |
| 26 | +- First-class standalone remediation route when the developer identifies drift at any stage. |
| 27 | +- Also serves as the default remediation handoff from `spec-kit-analyze` and `spec-kit-implement`. |
| 28 | +- Produces reconciled artifacts and next-step routing based on the updated artifact state. |
| 29 | + |
| 30 | +## Critical Constraints |
| 31 | + |
| 32 | +- Never create a new feature branch and never run feature-creation scripts. |
| 33 | +- Keep edits targeted; preserve artifact structure and heading order. |
| 34 | +- Prefer append-only updates for `tasks.md`; do not renumber existing tasks. |
| 35 | +- Run at most one clarification round (maximum 5 questions). |
| 36 | +- Keep unresolved `NEEDS CLARIFICATION` markers to 3 or fewer. |
| 37 | + |
| 38 | +## Preconditions |
| 39 | + |
| 40 | +- Run from repository root (or a subdirectory inside it). |
| 41 | +- Active feature context resolves to one `specs/<feature>/` directory. |
| 42 | +- User provides a concrete gap report (symptoms, mismatches, missing wiring, and/or scope hints like `plan-only` or `tasks-only`). |
| 43 | + |
| 44 | +## Workflow |
| 45 | + |
| 46 | +1. Validate reconcile input: |
| 47 | + |
| 48 | + - If no gap report is provided, stop with `ERROR: No gap report provided`. |
| 49 | + - Parse user scope constraints (for example `spec-only`, `plan-only`, `tasks-only`) and preserve them throughout. |
| 50 | + |
| 51 | +2. Resolve artifact paths exactly once: |
| 52 | + |
| 53 | + - Run `scripts/check-prerequisites.sh --json --paths-only --include-tasks` exactly once. |
| 54 | + - Parse: |
| 55 | + - `REPO_ROOT` |
| 56 | + - `BRANCH` |
| 57 | + - `FEATURE_DIR` |
| 58 | + - `FEATURE_SPEC` |
| 59 | + - `IMPL_PLAN` |
| 60 | + - `TASKS` |
| 61 | + - Validate required files: |
| 62 | + - If `FEATURE_SPEC` is missing, route to `spec-kit-specify`. |
| 63 | + - If `IMPL_PLAN` is missing, route to `spec-kit-plan`. |
| 64 | + |
| 65 | +3. Load reconcile context: |
| 66 | + |
| 67 | + - Required: `spec.md`, `plan.md`. |
| 68 | + - Optional (when present): `tasks.md`, `data-model.md`, `contracts/`, `research.md`, `quickstart.md`. |
| 69 | + - Load `memory/constitution.md` and enforce its MUST-level constraints. |
| 70 | + - If `memory/constitution.md` is missing, stop and route to `spec-kit-constitution`. |
| 71 | + |
| 72 | +4. Normalize the gap report into actionable items: |
| 73 | + |
| 74 | + - For each gap, capture: |
| 75 | + - `Title` |
| 76 | + - `Category` |
| 77 | + - `Evidence` |
| 78 | + - `Desired Outcome` |
| 79 | + - `Severity (HIGH|MEDIUM|LOW)` |
| 80 | + - Preferred categories: |
| 81 | + - `Navigation/Wiring` |
| 82 | + - `Integration/Contracts` |
| 83 | + - `Validation & UX` |
| 84 | + - `Authorization/Permissions` |
| 85 | + - `Test Coverage` |
| 86 | + - `Non-Functional` |
| 87 | + - `Docs` |
| 88 | + |
| 89 | +5. Clarify once when needed: |
| 90 | + |
| 91 | + - Ask questions only when answers change scope, UX behavior, acceptance criteria, or remediation cost. |
| 92 | + - Ask at most 5 total questions in one round, then proceed. |
| 93 | + - If an `askQuestions`-style tool exists in the current runtime, prefer it for this step to collect all multiple-choice answers in one fast interaction. |
| 94 | + - When using `askQuestions`, provide 2-5 mutually exclusive options per question, put the recommended option first, and allow a short custom response path. |
| 95 | + - If no `askQuestions` tool exists, fall back to the markdown prompt format below. |
| 96 | + - Use this format for each question: |
| 97 | + |
| 98 | +```markdown |
| 99 | +## Question [N]: [Topic] |
| 100 | + |
| 101 | +**Context**: [Relevant spec/plan/tasks excerpt or summary] |
| 102 | +**Decision Needed**: [Single-sentence decision] |
| 103 | +**Suggested Answers**: |
| 104 | + |
| 105 | +| Option | Answer | Implications | |
| 106 | +|--------|--------|--------------| |
| 107 | +| A | [Option A] | [Impact] | |
| 108 | +| B | [Option B] | [Impact] | |
| 109 | +| C | [Option C] | [Impact] | |
| 110 | +| Custom | Provide your own | [How it changes scope] | |
| 111 | + |
| 112 | +**Your choice**: _[Wait for user response]_ |
| 113 | +``` |
| 114 | + |
| 115 | +6. Map impact per artifact: |
| 116 | + |
| 117 | + - `spec.md`: user stories, acceptance criteria, user-visible scenarios, edge behaviors. |
| 118 | + - `plan.md`: architecture/modules, routing/navigation, integration contracts, testing strategy. |
| 119 | + - `tasks.md`: remediation work with exact file paths and ordering. |
| 120 | + - Respect scope constraints and explicitly mark skipped artifacts. |
| 121 | + |
| 122 | +7. Apply targeted edits: |
| 123 | + |
| 124 | + - `spec.md`: |
| 125 | + - Update only impacted sections. |
| 126 | + - Add a concise `Revisions` note (timestamp + reason). |
| 127 | + - `plan.md`: |
| 128 | + - Update only sections needed for reconciliation. |
| 129 | + - Keep design-level detail; do not add implementation patch instructions. |
| 130 | + - `tasks.md`: |
| 131 | + - If it exists, append remediation tasks using `NextID = max(T###) + 1`. |
| 132 | + - Preserve existing phases; add `Remediation: Gaps` phase when cross-cutting tasks are needed. |
| 133 | + - If it does not exist, create a minimal remediation-focused `tasks.md` from: |
| 134 | + 1. `{REPO_ROOT}/templates/tasks-template.md` |
| 135 | + 2. `{REPO_ROOT}/.specify/templates/tasks-template.md` |
| 136 | + 3. fallback: `{REPO_ROOT}/skills/spec-kit-tasks/assets/tasks-template.md` |
| 137 | + - For wiring/flow gaps, always include integration test tasks. |
| 138 | + |
| 139 | +8. Validate outputs: |
| 140 | + |
| 141 | + - No branch changes or feature-creation actions occurred. |
| 142 | + - Updated artifacts remain structurally valid and internally consistent. |
| 143 | + - Task formatting stays strict: `- [ ] T### [P?] [US#?] Action with exact file path`. |
| 144 | + |
| 145 | +9. Report reconciliation result: |
| 146 | + |
| 147 | + - Provide a Sync Impact Report with: |
| 148 | + - changed files (absolute paths) |
| 149 | + - summary of edits by artifact |
| 150 | + - new task IDs |
| 151 | + - skipped artifacts due to scope constraints |
| 152 | + - outstanding `NEEDS CLARIFICATION` markers (maximum 3) |
| 153 | + - confirmation that constitution constraints were respected |
| 154 | + - Recommend next step based on gates (`spec-kit-plan`, `spec-kit-tasks`, or `spec-kit-implement`). |
| 155 | + |
| 156 | +## Output |
| 157 | + |
| 158 | +- Updated reconciliation artifacts (`spec.md`, `plan.md`, and/or `tasks.md`) in the active feature directory. |
| 159 | +- New remediation tasks ready for execution. |
| 160 | +- Sync Impact Report for traceability. |
| 161 | + |
| 162 | +## Key Rules |
| 163 | + |
| 164 | +- Keep reconciliation incremental and focused on stated gaps. |
| 165 | +- Prefer appending over rewriting existing artifacts. |
| 166 | +- Never reorder existing task IDs. |
| 167 | +- Do not silently expand feature scope beyond the gap report and answered clarifications. |
| 168 | + |
| 169 | +## Common Mistakes |
| 170 | + |
| 171 | +- Running reconcile without a concrete gap report. |
| 172 | +- Rewriting whole artifacts instead of targeted updates. |
| 173 | +- Creating a new feature branch for remediation work. |
| 174 | +- Adding vague remediation tasks without exact file paths or acceptance intent. |
| 175 | +- Ignoring constitution MUST constraints while patching artifacts. |
| 176 | + |
| 177 | +## References |
| 178 | + |
| 179 | +- `scripts/check-prerequisites.sh` |
| 180 | +- `references/spec-kit-workflow.dot` |
| 181 | +- `https://github.com/github/spec-kit/issues/1063` |
| 182 | +- `https://github.com/user-attachments/files/23166782/reconcile.md` |
0 commit comments