Skip to content

Commit e44a692

Browse files
author
ahgraber
committed
feat(spec-kit-reconcile): add 'reconcile' skill for spec drift reconciliation
Inspired by github/spec-kit#1063 AI-assistant: OpenAI Codex
1 parent 90296bd commit e44a692

16 files changed

Lines changed: 1034 additions & 631 deletions

File tree

‎skills/spec-kit-analyze/SKILL.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,14 @@ Run a non-destructive cross-artifact quality audit before implementation.
1616
## When Not to Use
1717

1818
- Any prerequisite artifact is missing (`spec-kit-specify`, `spec-kit-plan`, or `spec-kit-tasks` first).
19-
- You want to fix artifacts directly rather than run analysis (`spec-kit-specify`, `spec-kit-plan`, `spec-kit-tasks`).
19+
- You need targeted remediation edits now (`spec-kit-reconcile`).
2020
- You are executing implementation work (`spec-kit-implement`).
2121

2222
## Router Fit
2323

2424
- Primary route from `spec-kit` after `spec-kit-tasks`.
2525
- Read-only quality gate before `spec-kit-implement`.
26+
- Default handoff to `spec-kit-reconcile` when findings require coordinated artifact updates.
2627

2728
## Critical Constraints
2829

@@ -81,12 +82,13 @@ Run a non-destructive cross-artifact quality audit before implementation.
8182

8283
6. Recommend next actions:
8384

84-
- If `CRITICAL` exists, block `spec-kit-implement` and route to the owning upstream skill.
85+
- If `CRITICAL`/`HIGH` findings require cross-artifact edits, block `spec-kit-implement` and route to `spec-kit-reconcile` with a concise gap summary.
86+
- If only one artifact needs focused updates, route to its owner skill (`spec-kit-specify`, `spec-kit-plan`, or `spec-kit-tasks`).
8587
- Otherwise provide prioritized improvements and whether implementation can proceed.
8688

8789
7. Offer follow-up only:
8890

89-
- Ask whether to propose concrete remediation edits for top findings.
91+
- Ask whether to run `spec-kit-reconcile` using top findings as the gap report.
9092
- Do not apply any edits in this skill.
9193

9294
## Output

‎skills/spec-kit-clarify/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Resolve high-impact ambiguity in the active feature specification before plannin
1818
- No feature spec exists yet (`spec-kit-specify` first).
1919
- Work is design decomposition (`spec-kit-plan`) or task generation (`spec-kit-tasks`).
2020
- You only need read-only consistency analysis (`spec-kit-analyze`).
21+
- You are reconciling broader cross-artifact drift (`spec-kit-reconcile`).
2122

2223
## Router Fit
2324

‎skills/spec-kit-implement/SKILL.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,13 @@ Execute approved feature tasks in dependency order and keep `tasks.md` status ac
1818
- `tasks.md` does not exist yet (`spec-kit-tasks` first).
1919
- You are still writing or revising requirements/design artifacts (`spec-kit-specify`, `spec-kit-clarify`, `spec-kit-plan`).
2020
- You need read-only consistency analysis rather than execution (`spec-kit-analyze`).
21+
- You need coordinated artifact remediation after gaps are discovered (`spec-kit-reconcile`).
2122

2223
## Router Fit
2324

2425
- Primary route from `spec-kit` after `spec-kit-tasks`.
2526
- Requires planning + task artifacts for the active feature branch.
26-
- Feeds back to `spec-kit-tasks`/`spec-kit-plan` only when execution reveals artifact gaps.
27+
- Routes execution-discovered artifact drift to `spec-kit-reconcile`.
2728

2829
## Preconditions
2930

@@ -89,7 +90,7 @@ Execute approved feature tasks in dependency order and keep `tasks.md` status ac
8990
- All required tasks are complete.
9091
- Implementation aligns with `spec.md`/`plan.md` intent.
9192
- Required tests/validation pass per project constraints.
92-
- If gaps remain, report blockers and route to the owning upstream skill when needed.
93+
- If gaps remain (for example missing wiring, acceptance mismatch, integration drift), route to `spec-kit-reconcile` with a concrete gap report.
9394

9495
9. Report implementation result:
9596

@@ -110,6 +111,7 @@ Execute approved feature tasks in dependency order and keep `tasks.md` status ac
110111
- Never mark a task `[X]` before its work and validations are complete.
111112
- Do not run `[P]` tasks concurrently when they touch the same files or dependent resources.
112113
- Stop and reroute when prerequisite artifacts are missing or invalid.
114+
- Do not patch spec/plan/tasks ad hoc during execution; use `spec-kit-reconcile` for structured remediation.
113115

114116
## Common Mistakes
115117

@@ -118,6 +120,7 @@ Execute approved feature tasks in dependency order and keep `tasks.md` status ac
118120
- Forgetting immediate `[X]` updates in `tasks.md`, causing drift between reality and artifact state.
119121
- Running `[P]` tasks together despite file/dependency conflicts.
120122
- Continuing past critical sequential failures instead of stopping and reporting.
123+
- Editing `spec.md`/`plan.md`/`tasks.md` informally during implementation instead of routing remediation through `spec-kit-reconcile`.
121124

122125
## References
123126

‎skills/spec-kit-implement/assets/spec-kit-implement-flow.svg‎

Lines changed: 250 additions & 228 deletions
Loading

‎skills/spec-kit-implement/references/spec-kit-implement-flow.dot‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ digraph spec_kit_implement {
6363
q_aligns_spec [label="Implementation aligns\nwith spec and plan?", shape=diamond];
6464
q_tests_pass [label="Tests and validation\npass?", shape=diamond];
6565
state_gaps [label="Gaps or failures\ndetected", shape=ellipse];
66+
act_reconcile [label="Run spec-kit-reconcile\nwith concrete gap report", shape=box];
6667

6768
// ── Final output ───────────────────────────────────────
6869
act_report_status [label="Report implementation\nstatus summary", shape=box];
@@ -133,7 +134,9 @@ digraph spec_kit_implement {
133134
q_tests_pass -> state_gaps [label="no, failures"];
134135

135136
// ── Gap remediation loop ───────────────────────────────
136-
state_gaps -> q_tasks_remain [label="address gaps\nand re-verify", style=dotted];
137+
state_gaps -> q_tasks_remain [label="execution-only fix\nand re-verify", style=dotted];
138+
state_gaps -> act_reconcile [label="artifact drift", style=dotted];
139+
act_reconcile -> q_tasks_exist [label="re-run implement\ngate", style=dotted];
137140

138141
// ── Done ───────────────────────────────────────────────
139142
act_report_status -> done;

‎skills/spec-kit-plan/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Generate implementation design artifacts from the approved feature specification
1919
- High-impact ambiguity in `spec.md` still blocks architecture or validation decisions (`spec-kit-clarify` first).
2020
- You are decomposing design into executable work items (`spec-kit-tasks`).
2121
- You only need a read-only consistency audit (`spec-kit-analyze`).
22+
- You are reconciling cross-artifact drift discovered mid-work (`spec-kit-reconcile`).
2223

2324
## Router Fit
2425

‎skills/spec-kit-reconcile/SKILL.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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`
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../spec-kit/references/spec-kit-workflow.dot
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../spec-kit/scripts/check-prerequisites.sh
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../spec-kit/scripts/common.sh

0 commit comments

Comments
 (0)