Auto-Reconciliation

Spec Kit automatically detects conflicts between your artifacts whenever you create or update a spec. This prevents contradictions from accumulating and ensures all your specifications stay consistent as the project grows.

How It Works

After every spec-modifying command (/speckit.specify, /speckit.clarify, /speckit.constitution, /speckit.brand, /speckit.infra, /speckit.design), the /speckit.reconcile command runs automatically. It:

1. Reads the artifact you just created or modified
2. Scans all existing specs, plans, tasks, constitution, branding, and infrastructure
3. Detects conflicts, contradictions, and inconsistencies
4. Asks you how to resolve each conflict interactively
5. Logs every decision for future reference

Detection Passes

The reconciler runs 7 focused detection passes, ordered by severity:

1. Contradiction Detection [CRITICAL]

Direct logical conflicts between artifacts:

• Spec A says "use PostgreSQL" but Spec B says "use MongoDB exclusively"
• Spec A says "users can delete accounts" but Spec B says "accounts are never deleted"
• Conflicting data model field definitions across specs
• Conflicting API contract definitions

2. Constitution Violations [CRITICAL]

New content that violates established MUST/SHALL principles:

• Adding a REST endpoint when the constitution mandates GraphQL
• Using a prohibited technology or pattern
• Violating security, accessibility, or performance requirements

WARNING

Constitution violations cannot be deferred. They must be resolved before proceeding.

3. Terminology Drift [HIGH]

Different terms for the same concept across specs:

• "customer" vs "user" vs "client" for the same entity
• "order" vs "purchase" vs "transaction"
• "active" vs "enabled" vs "live" for the same state

4. Scope Overlap [HIGH]

New spec covers functionality already specified elsewhere:

• Duplicate requirements across different feature specs
• Overlapping user stories or acceptance criteria
• Two specs independently specifying the same feature

5. Dependency Conflicts [MEDIUM]

Assumptions that contradict existing plans:

• New spec depends on a service not defined in any plan
• Assumes a data model field that doesn't exist
• Non-functional requirements exceeding infrastructure capacity

6. Branding & Design Inconsistency [MEDIUM]

Design specs not matching the branding specification:

• Hardcoded color values instead of design token references
• Font families not in the branding spec
• Spacing values not following the defined scale

7. Infrastructure Misalignment [MEDIUM]

Specs assuming capabilities not defined in the infrastructure:

• Assuming services not in the infra spec (e.g., Redis when only PostgreSQL exists)
• Assuming CI/CD capabilities not in the pipeline
• Assuming environments not defined (e.g., staging when only dev/prod exist)

Interactive Resolution

When conflicts are found, they're presented one at a time:

### Conflict 1 of 3: Terminology Drift [HIGH]

**What changed:**
> User profile spec defines "customer" as the primary actor

**Conflicts with:** `specs/001-auth/spec.md` — User Stories
> Auth spec uses "user" for the same entity across all requirements

**The issue:**
Two different terms ("customer" and "user") refer to the same entity.
This causes confusion in task breakdown and implementation.

**Options:**
| Option | Action |
|--------|--------|
| **A** | **Keep "customer"** — update auth spec to use "customer" |
| **B** | **Keep "user"** — update profile spec to use "user" |
| **C** | **Merge** — define both terms with clear distinction |
| **D** | **Defer** — log for future resolution |

You choose how to resolve each conflict:

Option	What happens
A Keep new	The existing artifact is updated to match your change
B Keep existing	Your new change is reverted to match the existing artifact
C Merge	You describe how to reconcile, the AI applies it to both
D Defer	Logged for future resolution, no files changed

Reconciliation Log

Every session is recorded in .specify/memory/reconciliation-log.md:

### 2026-02-24 Reconciliation Session

**Trigger:** /speckit.specify created specs/003-profile/spec.md
**Artifacts scanned:** 4 specs, constitution, branding, infra
**Conflicts found:** 3

| # | Category | Severity | Resolution | Details |
|---|----------|----------|------------|---------|
| 1 | Terminology Drift | HIGH | Resolved (B) | "customer" → standardized to "user" |
| 2 | Scope Overlap | HIGH | Resolved (C) | Merged auth and profile user stories |
| 3 | Dependency Conflict | MEDIUM | Deferred | Redis dependency unresolved |

Deferred conflicts are re-evaluated in the next reconciliation session involving the same artifacts.

Manual Usage

You can also run reconciliation manually at any time:

/speckit.reconcile

Without arguments, it scans for recently modified files and prompts you to choose which artifact to reconcile.

With arguments, specify the artifact:

/speckit.reconcile Check specs/003-profile/spec.md against all existing artifacts

Best Practices

• Don't defer constitution violations — they compound quickly and block implementation
• Standardize terminology early — run /speckit.constitution first to establish the glossary
• Review the reconciliation log periodically — deferred items may need attention
• Run after bulk changes — if you manually edit multiple specs, run /speckit.reconcile to catch cross-cutting issues