reconciled-spec-driven-development — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited reconciled-spec-driven-development (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
Do NOT use when:
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";
}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."
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.
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.
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:
When in doubt: compress the medium, preserve the shape.
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.
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.
Spec-kit gives RSDD almost everything it needs except the reconciliation arc. Build on it.
Reuse spec-kit primitives:
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 gradientComposition with spec-kit's existing commands:
/speckit.implement, run /cascade.detect against the resulting diff vs. the spec it claimed to implement./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.
| 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. |
| 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. |
docs/reconciliation/All of these mean: stop and re-read this skill.
| 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" |
github/spec-kit (releases, /speckit.* commands)spec-kit-reconcile, spec-kit-canon, Architecture Guard extensions~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.