RSDD — Reconciled Spec-Driven Development

A reasoning cascade that keeps spec and code aligned. Extends GitHub's spec-kit with the missing artifact↔code reconciliation arc.

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

What this is

Spec-Driven Development (as practiced by github/spec-kit) closes the loop from spec to code: a constitution, a spec, a plan, tasks, and an implementation step. What it does not yet close, in core, is the loop from code back to spec — the detection, reasoning, and resolution of drift that accumulates after implementation.

Spec-kit's own April 2026 newsletter names this as an open area:

"spec-level drift detection remains an open area … competitors differentiate on drift detection and orchestration depth"

RSDD is the proposed shape of that missing arc — a reconciliation cascade with reasoning at every gate, modeled on the Kubernetes controller pattern (desired state vs. actual state, with a reconciler closing the gap), adapted for the specific shape of evolving prose specs and evolving code.

The cascade

   ┌─────────────────┐
   │ change merged   │
   └────────┬────────┘
            ▼
   ┌─────────────────────────┐
   │ detector reasons        │
   │ over diff               │
   └────────┬────────────────┘
            ▼
       drift?  ── no ──▶ log, no-op
            │
           yes
            ▼
   ┌─────────────────────────────┐
   │ open reconciliation event   │
   └────────┬────────────────────┘
            ▼
   ┌─────────────────────────────┐
   │ conversational kickoff      │ ← load-bearing
   │ with human (or batched      │
   │ async doc under pressure)   │
   └────────┬────────────────────┘
            ▼
       direction agreed? ── no ──▶ escalate with reasoning
            │
           yes
            ▼
   ┌─────────────────────────────┐
   │ triage: agent within        │
   │ trust budget?               │
   └────────┬────────────────────┘
            │
       ┌────┴────┐
       ▼         ▼
   auto-resolve  escalate
       │         │
       └────┬────┘
            ▼
   ┌─────────────────────────────┐
   │ update trust gradient       │
   │ archive reasoning as corpus │
   └─────────────────────────────┘

Key principles

1. Drift is symmetric. Sometimes the code is the new truth. Sometimes the spec is. Sometimes the gap reveals a new requirement and both need a new layer. A cascade that defaults to one direction is broken.

2. Multi-layer spec awareness. Constitution / decision / plan / research / code each have different mutability and different auto-resolve eligibility. Constitution drift always escalates; tactical-plan drift is often routine.

3. Conversational kickoff is the contract. When drift is detected, the first move is a conversation between agent and human about which direction to reconcile — not a lint, not an issue, not a CI failure. The conversation has a seven-step shape (spec quote → code state → gap → three-direction analysis → proposal → alternatives → ask). The medium can be compressed (batch async doc, trust-class authorization) but the shape is preserved.

4. Trust gradient over time. The agent earns autonomy through track record. Day 1: escalate everything. Month 3: auto-resolve well-understood drift classes. Forever: constitution drift always escalates.

5. Reasoning trail as committed corpus. Every reconciliation event produces a reasoning document at docs/reconciliation/YYYY-MM-DD-NNN-*.md. Future agents read it the way they read ADRs.

Position relative to spec-kit

RSDD is designed to build on spec-kit, not replace it.

Spec-kit gives	RSDD adds
/speckit.constitution — governing principles	Constitution drift detection (always escalates)
/speckit.specify — what + why	Spec-vs-code direction reasoning
/speckit.clarify — conversational Q/A on underspec'd areas	Reconciliation kickoff (same shape, applied to drift gaps)
/speckit.plan — tech stack + architecture	Plan-layer drift handling (often auto-resolvable)
/speckit.tasks — task list	Trust-gradient calibration unit
/speckit.analyze — artifact↔artifact drift	/cascade.detect — artifact↔code drift (the missing direction)
/speckit.implement — execution	/cascade.kickoff, /cascade.triage, /cascade.resolve after merge

The cascade is intended to land as a spec-kit extension (and/or preset), composable with 29+ AI coding agents that spec-kit already supports.

Status

Component	Status
Skill (Claude Code)	✅ v0.1 — SKILL.md
Methodology naming	✅ RSDD; software = attended software
Conversational kickoff contract	✅ seven-step shape
Multi-layer spec awareness	✅ five layers (constitution / decision / plan / research / code)
Trust gradient model	✅ time-based, track-record-driven
spec-kit extension implementation	⬜ planned
spec-kit preset	⬜ planned
Reconciliation event template	⬜ in SKILL.md, not yet extracted
Reference implementation	⬜ first target: integrate with an existing ADR-using project

Using the skill

The skill is a Claude Code agent skill. Install by cloning into your Claude Code skills directory:

git clone https://github.com/jeremedia/rsdd.git ~/rsdd
mkdir -p ~/.claude/skills/reconciled-spec-driven-development
cp ~/rsdd/SKILL.md ~/.claude/skills/reconciled-spec-driven-development/SKILL.md

Or symlink for live updates:

ln -s ~/rsdd ~/.claude/skills/reconciled-spec-driven-development

Once installed, the skill auto-invokes when conversation hits its trigger conditions: spec drift, post-merge reconciliation, designing drift-detection workflows, integrating agents into spec-kit, or filing out-of-spec issues.

Prior art and adjacent work

• github/spec-kit — Spec-Driven Development core; RSDD extends, doesn't replace
• spec-kit-reconcile — community extension; surgical one-way spec updates from code
• spec-kit-canon — community preset; canon-driven workflows including spec-drift
• spec-kit-architecture-guard — community extension; architecture drift review
• Intent (proprietary) — living specs + automated drift detection
• Kubernetes controller pattern — structural ancestor of the cascade

Why "attended software"

Borrowed from a related project's canon: attention is what keeps matter from eating itself. Applied to software, attention is what keeps the gap between spec and code from compounding silently into an unrecognizable system. The cascade is the attention; attended software is the result.

License

MIT — see LICENSE.

Contributing

Status: early. Issues and discussion welcome.

---

RSDD is an experiment in closing the spec-code loop with reasoning rather than rules. If you build something on it, file an issue.