Rsdd

Reconciled Spec-Driven Development

Overview

Reconciled Spec-Driven Development (RSDD) is Spec-Driven Development with the missing arc closed: a reasoning cascade that continuously aligns the spec layer and the implementation layer, with conversational kickoff, multi-layer awareness, bidirectional drift handling, and a trust gradient that lets agents earn autonomy.

Software developed this way is attended software — software whose alignment between intent and manifestation is actively maintained by a reasoning loop, not assumed.

GitHub's spec-kit (/speckit.* commands) provides the conversational scaffolding for SDD across 29+ agents. RSDD extends spec-kit (or any equivalent ADR/RFC practice) by adding the artifact↔code reconciliation direction that spec-kit explicitly does not yet provide in core.

Core insight: drift is symmetric. Sometimes the code is wrong. Sometimes the spec is. Sometimes both are scoped correctly and the gap reveals a new requirement. The reconciliation cascade is a controller loop (k8s pattern) with a reasoning step at every gate — and the first move when drift is detected is a conversation, not an action.

Use this skill when

• A project has formal-ish spec artifacts and you're about to design a check/audit/CI step for spec-vs-code alignment
• An agent is about to file an "out-of-spec" issue and needs to do it well (with reasoning, direction, confidence, alternatives) rather than as a one-line lint
• A team is on spec-kit and asking how to handle "spec drift" (spec-kit's own term — they know it's an open gap)
• Conversation reaches the topic of "the code and the spec disagree, now what?"
• You're integrating multiple AI agents into a Q/A flow and need to know where reconciliation hooks attach
• You're being asked to encode a process for keeping an evolving artifact aligned with an evolving codebase

Do NOT use when:

• The "spec" is informal (chat logs, ad-hoc decisions). Build the spec layer first, then return to RSDD.
• The triage agent's track record is unknown and stakes are high. Run the cascade manually for a calibration period first.
• The codebase is a one-shot script with no long-term maintenance horizon.

The cascade

digraph cascade {
    rankdir=TB;
    "Change merged" [shape=box];
    "Detector reasons over diff" [shape=box];
    "Drift suspected?" [shape=diamond];
    "Open reconciliation event" [shape=box];
    "Conversational kickoff with human" [shape=box];
    "Direction agreed?" [shape=diamond];
    "Triage: can agent resolve unaided?" [shape=diamond];
    "Auto-resolve + commit reasoning trail" [shape=box];
    "Escalate with reasoning to human" [shape=box];
    "Update trust gradient from outcome" [shape=box];
    "Close event, archive as corpus" [shape=box];
    "No-op, log" [shape=box];

    "Change merged" -> "Detector reasons over diff";
    "Detector reasons over diff" -> "Drift suspected?";
    "Drift suspected?" -> "No-op, log" [label="no"];
    "Drift suspected?" -> "Open reconciliation event" [label="yes"];
    "Open reconciliation event" -> "Conversational kickoff with human";
    "Conversational kickoff with human" -> "Direction agreed?";
    "Direction agreed?" -> "Triage: can agent resolve unaided?" [label="yes"];
    "Direction agreed?" -> "Escalate with reasoning to human" [label="no / unclear"];
    "Triage: can agent resolve unaided?" -> "Auto-resolve + commit reasoning trail" [label="yes + within trust budget"];
    "Triage: can agent resolve unaided?" -> "Escalate with reasoning to human" [label="no / outside budget"];
    "Auto-resolve + commit reasoning trail" -> "Update trust gradient from outcome";
    "Escalate with reasoning to human" -> "Update trust gradient from outcome";
    "Update trust gradient from outcome" -> "Close event, archive as corpus";
}

The conversational kickoff (load-bearing)

When an agent detects suspected drift, the first move is not to file an issue, fail CI, or open a PR. The first move is to open a conversation. The conversation has a recognizable shape:

1. State the spec change (verbatim quote of the spec text + reference).
2. State the code state (verbatim diff or code reference).
3. Articulate the drift in one sentence (the gap).
4. Reason about direction:
   - Could the code be the new truth (and the spec needs to evolve)?
   - Could the spec be the standing truth (and the code needs to change)?
   - Could both be correct in scope and the gap reveal a new requirement?
5. Propose a reconciliation with a confidence level.
6. List alternatives considered, with one-line reasons.
7. Ask the human which direction to take (or, if confident and within trust budget, propose to proceed and commit the reasoning).

This shape is the contract. An agent that skips steps 4-6 has filed a lint, not a reconciliation event.

Why the conversation matters: the spec and the code are both writing surfaces. The drift event is itself an editorial moment — it's where the project gets to write down why it chose one direction over the other. That writing is corpus for future agents.

Where the kickoff lives on spec-kit: extend /speckit.clarify. Spec-kit's /speckit.clarify already does conversational Q/A about underspecified spec areas. RSDD's kickoff is the same shape, applied to the spec-vs-code gap: instead of "this part of the spec is underspecified, let me ask," it's "this part of the code disagrees with the spec, let me explain the gap and ask which direction we reconcile."

Multi-layer spec awareness

Spec artifacts are not uniform. Treating them as one undifferentiated corpus is the single biggest failure mode.

Layer	Spec-kit name	Mutability	Auto-resolve eligible?
Canon / principles	constitution	Rare, deliberate, never silent	No. Always escalate.
Decision	numbered ADR / spec	Supersedable via new ADR with status link	Sometimes, if drift is mechanical and trust is earned
Tactical	plan	Mutable, updated as execution discovers facts	Often, low stakes
Research / discovery	dated note	Immutable (point-in-time by convention)	N/A — drift against research is just "world moved on"
Code	implementation	Mutable	This is what the cascade reconciles

The detector must know which layer the drift is against and choose a default accordingly. Drift against the constitution is a stop-the-line event; drift against a plan is often routine.

Drift direction is symmetric

The fork in the conversational kickoff is the most important reasoning step. Three cases, all common:

Code is the new truth. The implementer discovered a constraint or capability the spec didn't account for. The spec should catch up. Example: ADR 0008 said "SQLite, can move to pg later." A PR added pgvector. Code is right; spec needs supersession. Reconciliation = draft a new ADR with the new substrate decision and supersession link.

Spec is the standing truth. The implementer violated a load-bearing constraint, often because they didn't read the spec or misunderstood it. Reconciliation = revert or rework code, possibly add a note about why the constraint exists so the next implementer doesn't repeat the mistake.

Both are correct in scope. The spec covers one context, the code is in another, and the gap reveals a missing distinction. Reconciliation = neither revert nor supersede; add a new spec layer (chapter, scope qualifier, conditional) that names both situations.

A cascade that defaults to one direction without reasoning about all three is broken.

Compressing the kickoff (not skipping it)

Under release pressure or high drift volume, the temptation is to skip the conversational kickoff. Don't skip it. Compress it.

The kickoff shape (the seven steps) is the contract. The medium of delivery is negotiable:

Pressure	Compressed kickoff	Still required
Many small drifts in one layer	Single async batch document, one entry per drift, human approves in one pass	Each drift gets all seven steps; reasoning per drift, not per batch
Recurring identical drift pattern	Trust-gradient authorization to auto-resolve this class; reasoning trail still committed	The authorization itself is a kickoff event; the human approved the class, not each instance
Time-critical release	Async kickoff (no synchronous meeting)	Document is still produced; human still approves; reasoning trail still committed

What compression never licenses:

• Skipping the reasoning trail (the corpus value comes from the trail)
• Skipping the direction analysis (the three-direction reasoning is the load-bearing step)
• Batching across spec layers (constitution drift never shares a kickoff doc with plan drift)
• Auto-resolving constitution-layer drift, ever

When in doubt: compress the medium, preserve the shape.

Trust gradient

The triage gate decides "can the agent resolve this without human review?" The answer changes over time.

Day 1:        Escalate everything. Agent files reasoning, human resolves.
Week 2:       Auto-resolve mechanical cases (typo in spec quoted text, renamed identifier).
Month 1:      Auto-resolve low-stakes plan-layer drift if direction is unambiguous.
Month 3+:     Auto-resolve well-understood decision-layer drift; constitution still escalates.
Forever:      Constitution drift always escalates. Major architecture shifts always escalate.

Trust is earned by a track record. Every reconciliation event becomes a record: did the agent's resolution stick? Was it reverted? Did a human override it? The trust gradient is computed (or at minimum, periodically reviewed) from that record.

The agent is a junior team member earning autonomy. Treat it accordingly.

Reasoning as committed artifact

Every reconciliation event produces a reasoning trail. That trail is corpus, not garbage. It belongs in the repo, not in a transient JSONL log.

Recommended location: docs/reconciliation/YYYY-MM-DD-NNN-short-slug.md. One file per event. Format:

---
event: 2026-05-22-001
status: resolved | escalated | open
trigger: post-merge | scheduled | manual | conversation
spec_layer: constitution | decision | plan | research
direction: code-is-truth | spec-is-truth | both-need-new-layer
confidence: high | medium | low
resolver: agent | human | both
---

# Drift: <one-line summary>

## Spec state
<verbatim quote + reference>

## Code state
<verbatim diff or code reference>

## The gap
<one sentence>

## Direction reasoning
<the agent's analysis of all three cases — code-truth, spec-truth, new-layer>

## Resolution
<what was done, by whom, with what reasoning>

## Alternatives considered
- <option> — <why not>
- <option> — <why not>

Future agents reading the repo learn from this trail the same way they learn from ADRs and commit messages. The trail is one of the project's load-bearing knowledge surfaces.

Integration with spec-kit

Spec-kit gives RSDD almost everything it needs except the reconciliation arc. Build on it.

Reuse spec-kit primitives:

• Constitution = canon layer
• Specify = decision layer (per feature)
• Plan = tactical layer
• Tasks = execution unit
• Clarify = conversational shape (RSDD extends this for drift conversations)
• Analyze = artifact↔artifact drift detector (RSDD adds artifact↔code direction)

Add (as a spec-kit extension or preset):

• /cascade.detect — runs reasoning detector against a diff or full tree, emits suspected drift candidates
• /cascade.kickoff — opens a reconciliation event with the conversational shape above
• /cascade.triage — applies trust gradient + spec-layer awareness, decides escalate vs. auto-resolve
• /cascade.resolve — performs the agreed action (supersede ADR, draft new layer, edit code), commits the reasoning trail
• /cascade.review-trust — reviews recent reconciliation events to update trust gradient

Composition with spec-kit's existing commands:

• After /speckit.implement, run /cascade.detect against the resulting diff vs. the spec it claimed to implement.
• When /speckit.analyze finds artifact-artifact drift, it can hand off to /cascade.kickoff for the conversational resolution.
• /speckit.constitution changes always trigger /cascade.detect against the full codebase (high stakes).

The community extension spec-kit-reconcile (stn1slv) does surgical one-way updates of spec from code. RSDD generalizes: bidirectional, reasoned, conversational, with trust gradient. They are compatible — spec-kit-reconcile can be one of the resolver implementations.

Common mistakes

Mistake	What goes wrong	Fix
Treat drift as code-violating-spec by default	Code that's actually the new truth gets reverted; spec ossifies	Always reason about direction explicitly before action
One severity tier for all spec layers	Constitution drift gets auto-resolved silently; tactical drift gets escalated and creates noise	Multi-layer awareness, different defaults per layer
Lint-style drift reports	Useless one-line "ADR 0008 mentions SQLite, code uses pgvector" — no direction, no proposal, no alternatives	Reasoning surface contract (see kickoff shape)
Pre-commit hooks	Bypassable with --no-verify; runs on author's machine; hard to give it the context it needs	Post-merge (or pre-merge on a CI runner with full repo access)
Static trust calibration	Either too noisy forever or too permissive forever	Dynamic trust gradient, reviewed against actual resolution outcomes
Reasoning trail as JSONL only	Future humans can't read it; future agents skip it as "logs"	Markdown files committed to docs/reconciliation/
Bypass conversational kickoff for "obvious" cases	Cases that seem obvious to the agent often aren't; the human catches the third-direction case agents miss	The conversational kickoff is the contract. Skip it only after the trust gradient has explicitly authorized auto-resolve for this class of drift.

Counter-rationalizations

Rationalization	Reality
"The drift is obvious, just file the issue"	Filing without the reasoning contract creates noise and erodes trust. The reasoning is the value.
"Conversational kickoff is too slow for routine drift"	Compress the medium (batch async doc, one entry per drift); never skip the shape. For repeating classes, earn trust-gradient authorization so the class itself becomes the kickoff event.
"We have 23 drifts this sprint, no time for kickoffs"	Stratify by layer first (the count usually collapses). Compress the kickoff for the survivors (one async doc, one entry per drift). Constitution drift never batches.
"ADRs are immutable, we just need to enforce them"	ADRs are supersedable by design. RSDD's job is to surface when supersession is needed, not to ossify the spec.
"We can do this with regex/static checks"	Static checks catch keyword presence. They cannot reason about direction (which side is right). That's the work.
"Auto-resolve once trust is earned" should mean auto-merge	Auto-resolve commits a draft and reasoning trail; the merge can still go through normal review. Resolution and merge are separate gates.
"Spec-kit doesn't have this, so we don't need it"	Spec-kit explicitly calls drift detection an open gap. Their /speckit.analyze only covers artifact↔artifact; the artifact↔code direction is missing.
"This is just over-engineered linting"	Linting answers "does this match the rule?" RSDD answers "the spec and the code disagree — which is right, and what do we change?" Different question, different shape.

Red flags — stop and re-read the skill

• About to file an "out-of-spec" issue without the reasoning surface contract
• About to auto-resolve drift against the constitution / canon layer
• Designing a one-shot audit instead of a controller loop
• Conversational kickoff is being skipped because "the drift is obvious"
• Trust gradient is static (or doesn't exist)
• Drift reports are going to a JSONL log instead of docs/reconciliation/
• Defaulting to "code violates spec, fix the code" without considering the other two directions
• Treating all spec layers (constitution, decision, plan, research) as one corpus

All of these mean: stop and re-read this skill.

Quick reference

You see...	Do...
Code merged that contradicts an ADR	Open reconciliation event, reason about all three drift directions before proposing
Constitution change	Trigger /cascade.detect against full codebase, escalate every finding
Spec-kit project with no drift detection	Add /cascade.* extension commands as a preset
ADR-only project (no spec-kit)	Build the cascade directly; spec-kit integration is nice-to-have, not required
"Should we auto-fix this?"	Check trust gradient + spec layer; default escalate unless both authorize
Multiple drifts at once	One reconciliation event per drift; do not batch — each needs its own reasoning trail
Drift the agent can't reason about	Escalate with verbatim spec quote + verbatim code state + explicit "I cannot determine direction"

Background reading

• Spec-kit: github/spec-kit (releases, /speckit.* commands)
• Spec-kit on drift: April 2026 newsletter explicitly names drift detection as an open gap
• Community prior art: spec-kit-reconcile, spec-kit-canon, Architecture Guard extensions
• Kubernetes controller pattern (the structural ancestor of the cascade): reconciliation loop with desired-state vs. actual-state
• Spine (in our project corpus): AI edit reviewer as the book's immune system — RSDD applied to a manuscript