Spec Kit Reconcile

Close specification drift by updating existing Spec Kit artifacts in-place.

Invocation Notice

• Inform the user when this skill is being invoked by name: spec-kit-reconcile.

When to Use

• You discover specification drift at any stage (specify, clarify, plan, tasks, analyze, or implement) and need artifacts realigned before continuing.
• Code exists, but behavior still misses expected flows (routing/navigation wiring, integration handoff, validation UX, coverage gaps).
• spec-kit-analyze found issues that require coordinated edits across spec.md, plan.md, and tasks.md.
• You need targeted remediation planning without creating a new feature branch.

When Not to Use

• You need a brand-new feature spec (spec-kit-specify first).
• You need first-pass design decomposition from an approved spec (spec-kit-plan first).
• You only need a read-only audit (spec-kit-analyze).
• You are only executing already-correct tasks (spec-kit-implement).

Router Fit

• First-class standalone remediation route when the developer identifies drift at any stage.
• Also serves as the default remediation handoff from spec-kit-analyze and spec-kit-implement.
• Produces reconciled artifacts and next-step routing based on the updated artifact state.

Critical Constraints

• Never create a new feature branch and never run feature-creation scripts.
• Keep edits targeted; preserve artifact structure and heading order.
• Prefer append-only updates for tasks.md; do not renumber existing tasks.
• Run at most one clarification round (maximum 5 questions).
• Keep unresolved NEEDS CLARIFICATION markers to 3 or fewer.

Preconditions

• Run from repository root (or a subdirectory inside it).
• Active feature context resolves to one specs/<feature>/ directory.
• User provides a concrete gap report (symptoms, mismatches, missing wiring, and/or scope hints like plan-only or tasks-only).

Workflow

1. Validate reconcile input:

• If no gap report is provided, stop with ERROR: No gap report provided.
• Parse user scope constraints (for example spec-only, plan-only, tasks-only) and preserve them throughout.

1. Resolve artifact paths exactly once:

• Run scripts/check-prerequisites.sh --json --paths-only --include-tasks exactly once.
• Parse:
• REPO_ROOT
• BRANCH
• FEATURE_DIR
• FEATURE_SPEC
• IMPL_PLAN
• TASKS
• Validate required files:
• If FEATURE_SPEC is missing, route to spec-kit-specify.
• If IMPL_PLAN is missing, route to spec-kit-plan.

1. Load reconcile context:

• Required: spec.md, plan.md.
• Optional (when present): tasks.md, data-model.md, contracts/, research.md, quickstart.md.
• Load memory/constitution.md and enforce its MUST-level constraints.
• If memory/constitution.md is missing, stop and route to spec-kit-constitution.

1. Normalize the gap report into actionable items:

• For each gap, capture:
• Title
• Category
• Evidence
• Desired Outcome
• Severity (HIGH|MEDIUM|LOW)
• Preferred categories:
• Navigation/Wiring
• Integration/Contracts
• Validation & UX
• Authorization/Permissions
• Test Coverage
• Non-Functional
• Docs

1. Clarify once when needed:

• Ask questions only when answers change scope, UX behavior, acceptance criteria, or remediation cost.
• Ask at most 5 total questions in one round, then proceed.
• 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.
• When using askQuestions, provide 2-5 mutually exclusive options per question, put the recommended option first, and allow a short custom response path.
• If no askQuestions tool exists, fall back to the markdown prompt format below.
• Use this format for each question:

## Question [N]: [Topic]

**Context**: [Relevant spec/plan/tasks excerpt or summary]
**Decision Needed**: [Single-sentence decision]
**Suggested Answers**:

| Option | Answer | Implications |
|--------|--------|--------------|
| A | [Option A] | [Impact] |
| B | [Option B] | [Impact] |
| C | [Option C] | [Impact] |
| Custom | Provide your own | [How it changes scope] |

**Your choice**: _[Wait for user response]_

1. Map impact per artifact:

• spec.md: user stories, acceptance criteria, user-visible scenarios, edge behaviors.
• plan.md: architecture/modules, routing/navigation, integration contracts, testing strategy.
• tasks.md: remediation work with exact file paths and ordering.
• Respect scope constraints and explicitly mark skipped artifacts.

1. Apply targeted edits:

• spec.md:
• Update only impacted sections.
• Add a concise Revisions note (timestamp + reason).
• plan.md:
• Update only sections needed for reconciliation.
• Keep design-level detail; do not add implementation patch instructions.
• tasks.md:
• If it exists, append remediation tasks using NextID = max(T###) + 1.
• Preserve existing phases; add Remediation: Gaps phase when cross-cutting tasks are needed.
• If it does not exist, create a minimal remediation-focused tasks.md from:

1. {REPO_ROOT}/templates/tasks-template.md
2. {REPO_ROOT}/.specify/templates/tasks-template.md
3. fallback: {REPO_ROOT}/skills/spec-kit-tasks/assets/tasks-template.md

• For wiring/flow gaps, always include integration test tasks.

1. Validate outputs:

• No branch changes or feature-creation actions occurred.
• Updated artifacts remain structurally valid and internally consistent.
• Task formatting stays strict: - [ ] T### [P?] [US#?] Action with exact file path.

1. Report reconciliation result:

• Provide a Sync Impact Report with:
• changed files (absolute paths)
• summary of edits by artifact
• new task IDs
• skipped artifacts due to scope constraints
• outstanding NEEDS CLARIFICATION markers (maximum 3)
• confirmation that constitution constraints were respected
• Recommend next step based on gates (spec-kit-plan, spec-kit-tasks, or spec-kit-implement).

Output

• Updated reconciliation artifacts (spec.md, plan.md, and/or tasks.md) in the active feature directory.
• New remediation tasks ready for execution.
• Sync Impact Report for traceability.

Key Rules

• Keep reconciliation incremental and focused on stated gaps.
• Prefer appending over rewriting existing artifacts.
• Never reorder existing task IDs.
• Do not silently expand feature scope beyond the gap report and answered clarifications.

Common Mistakes

• Running reconcile without a concrete gap report.
• Rewriting whole artifacts instead of targeted updates.
• Creating a new feature branch for remediation work.
• Adding vague remediation tasks without exact file paths or acceptance intent.
• Ignoring constitution MUST constraints while patching artifacts.

References

• scripts/check-prerequisites.sh
• references/spec-kit-workflow.dot
• https://github.com/github/spec-kit/issues/1063
• https://github.com/user-attachments/files/23166782/reconcile.md