Feature: /speckit.reconcile — close post‑implementation gaps by asking clarifying questions, then amending spec.md, plan.md, and tasks.md

[MDean-Slalom]

Summary

There’s no first‑class way to reconcile post‑implementation gaps after running /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement. This creates artifact drift: example scenario; the backend and tests may exist and a UI may be scaffolded, but navigation/wiring or updated acceptance criteria are missing. I’m proposing a focused command template, /speckit.reconcile, to ask targeted questions and then amend spec.md, plan.md, and tasks.md accordingly—without creating a new feature branch.

---

Problem

• Implementations land but users can’t reach the new screens (routes/menu entries missing).
• Acceptance criteria and user scenarios are not updated to match shipped behavior.
• Tasks don’t reflect the cleanup work (integration tests, wiring, docs), so gaps recur.
• Current flow lacks a structured, low‑risk loop to fix these quickly.

---

Why this matters

• Prevents spec/plan/tasks drift and keeps artifacts trustworthy.
• Eliminates wasteful re‑spec/plan cycles for small but critical fixes.
• Produces ready‑to‑implement tasks that /speckit.implement can pick up immediately.
• Small, template‑only surface area (no CLI changes, minimal blast radius).

---

Proposal

New command: /speckit.reconcile
Location: templates/commands/reconcile.md
Scope: Template‑only. Reuses existing discovery scripts; no branch ops, append/minimal edits.

High‑level flow:

1. Parse a user gap report ($ARGUMENTS).

2. Ask up to 5 clarifying questions once (only if scope/UX decisions materially change).

3. Apply targeted edits:

   • spec.md: user story + acceptance criteria + User Scenarios & Testing; add a short Revisions note.
   • plan.md: Routing & Navigation, Integration Contracts, Testing Strategy.
   • tasks.md: append new T### items under the right User Story phase (or a final “Remediation: Gaps” phase). Include exact file paths and optional [P].
   • Always add an integration test task when wiring/flows are the gap.

4. Output a Sync Impact Report listing changed files (absolute paths), new task IDs, and any outstanding decisions.

---

Behavior contract (concise)

• Use check-prerequisites to resolve FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN, and optional TASKS_FILE.
• Operate in place (no new feature, no branch switching).
• Absolute paths in all outputs.
• Append‑only where possible; preserve section order/headings.
• At most 3 NEEDS CLARIFICATION markers; otherwise pick reasonable defaults.

---

Out of scope

• No CLI/script changes; this is a template‑level addition.
• No branch management.
• No broad rewrites of existing artifacts—surgical edits only.

---

Acceptance criteria

• New file: templates/commands/reconcile.md.

• Running /speckit.reconcile "<gap report>" results in:

  • Updated spec.md and/or plan.md only where needed.
  • Appended tasks.md items with T###, [US#], optional [P], and exact file paths.
  • A printed Sync Impact Report with absolute paths, task IDs, and any outstanding decisions.

• Works with current check‑prerequisites discovery flow.

• No branch changes, minimal diffs, structure preserved.

---

Implementation sketch

• Add templates/commands/reconcile.md (preliminary draft attached).
• Keep edits section‑precise; avoid renumbering tasks.
• Where wiring is missing, enforce an integration test task to prove end‑to‑end navigation.

---

Risks & mitigations

• Over‑editing artifacts → Mitigate via append‑only, section‑targeted diffs, and a hard limit on clarifications.
• Template vs. CLI confusion → Clearly label as templates change; no executable changes.
• Task sprawl → Require exact file paths and story‑phase placement to keep tasks actionable.

---

Prior art / fit

This follows the project’s pattern of small, additive templates that improve the flow without touching the CLI. The command is composable and keeps the core loop fast.

---

Willing to implement

Yes—happy to open the PR and iterate on feedback.

---

Appendix — Example gap report ⇒ expected tasks

“Backend + tests for Invoice Settings exist; React screen scaffolded. Users can’t navigate to it. Need sidebar link + route. Success toasts must follow UX constitution.”

Expected new tasks (examples):

- [ ] T045 [US2] Add route /invoices/settings in frontend/src/router/index.ts
- [ ] T046 [US2] Add sidebar link to Invoice Settings in frontend/src/components/Sidebar.tsx
- [ ] T047 [US2] Integration test: navigate to Invoice Settings (tests/integration/invoices_settings.spec.ts)

reconcile.md

[armujahid]

I like this approach, Or we can also enhance "clarify" to update existing plan and tasks list (either by default or via some flags/sub-command).

Dedicated reconsile command is better that can be used even if we don't want to update spec.

[jellydn]

Great. I created an issue which is similar to this a while back and it's closed. Good to see others have the same thoughts.

FYI #675

[deepfriedmind]

Not once after running /speckit.implement has the agent checked off a single box in tasks.md before stopping and claiming success. There's so much context that the model loses track long before implementation is actually finished, nevermind remembering to tick boxes. I can only imagine what would happen if I didn't have rigorous checks in place for types/linting/dependencies/tests. Something like this is sorely needed.

[stn1slv]

Hi everyone 👋,

I really felt the pain point described in this issue regarding "artifact drift" after implementation. Since the Spec-Kit Extension API is now available, I went ahead and built a community extension that implements the exact workflow proposed in this issue so we can start closing these gaps today.

You can check it out here: stn1slv/spec-kit-reconcile

How it works

It provides a new command that takes a natural-language "Gap Report" directly as the argument:

/speckit.reconcile.run "Backend exists, but React screen is unreachable; need sidebar link and route"

It follows the requirements outlined in this issue:

1. In-place Edits: It surgically updates the active feature's spec.md and plan.md without creating new branches.
2. Actionable Tasks: It automatically finds the highest T### ID in tasks.md and appends new remediation tasks with exact file paths.
3. Mandatory Tests: It enforces the creation of integration test tasks for any reported wiring/navigation gaps.
4. Clarification: It asks up to 5 clarifying questions if the gap report is ambiguous.

Installation

If anyone wants to try it out, you can install it directly via the CLI:

specify extension add reconcile --from https://github.com/stn1slv/spec-kit-reconcile/archive/refs/tags/v1.0.0.zip

Future Deprecation

I built this primarily to unblock my own workflow right now. If/when the Spec-Kit core team decides to build a native /speckit.reconcile command that handles this lifecycle stage officially, I will happily deprecate this extension in favor of the built-in solution!

Hopefully, this is helpful to others running into the same artifact drift issues in the meantime.

[mnriem]

The reconcile functionality is now available as a community extension, delivered in #1844 — merged on March 16, 2026. Closing as completed.