import{_ as s,o as a,c as n,a2 as t}from"./chunks/framework.CJEbdX1t.js";const u=JSON.parse('{"title":"Living Specs","description":"","frontmatter":{},"headers":[],"relativePath":"concepts/living-specs.md","filePath":"concepts/living-specs.md"}'),i={name:"concepts/living-specs.md"};function o(p,e,l,c,r,d){return a(),n("div",null,[...e[0]||(e[0]=[t(`<h1 id="living-specs" tabindex="-1">Living Specs <a class="header-anchor" href="#living-specs" aria-label="Permalink to &quot;Living Specs&quot;">​</a></h1><p>The core engine that makes &quot;documentation that keeps up&quot; real is the feedback loop — a continuous cycle from spec authoring through code implementation back to spec updates.</p><h2 id="the-feedback-loop" tabindex="-1">The Feedback Loop <a class="header-anchor" href="#the-feedback-loop" aria-label="Permalink to &quot;The Feedback Loop&quot;">​</a></h2><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>PM writes spec (structured markdown) ─────────────────────┐</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Agent indexes all markdown (specs + docs + READMEs)        │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Agent creates tickets from spec sections                   │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Engineer writes code, opens PR                             │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Agent analyzes PR against ALL indexed docs                 │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Agent evaluates: does code realize spec intent?            │</span></span>
<span class="line"><span>  │  • Compares implementation against acceptance criteria  │</span></span>
<span class="line"><span>  │  • Checks for conflicts with existing docs             │</span></span>
<span class="line"><span>  │  • Flags undocumented behavior                         │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Coverage updates, spec status auto-transitions             │</span></span>
<span class="line"><span>  │  • Section marked &quot;done&quot; based on code analysis        │</span></span>
<span class="line"><span>  │  • Ticket closed when spec is realized                 │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Doc-update PRs generated for all affected markdown         │</span></span>
<span class="line"><span>  │  • Specs, READMEs, guides, ADRs — not just specs      │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Stale docs flagged when code changes but docs don&#39;t        │</span></span>
<span class="line"><span>  │                                                        │</span></span>
<span class="line"><span>  ▼                                                        │</span></span>
<span class="line"><span>Better indexed knowledge ──────────────────────────────────┘</span></span>
<span class="line"><span>  (richer context for the next PR analysis)</span></span></code></pre></div><h2 id="why-ticket-status-isn-t-enough" tabindex="-1">Why Ticket Status Isn&#39;t Enough <a class="header-anchor" href="#why-ticket-status-isn-t-enough" aria-label="Permalink to &quot;Why Ticket Status Isn&#39;t Enough&quot;">​</a></h2><p>The key insight: ticket status is a proxy. Code is the truth.</p><p>When a PR merges that implements §3.2 Retry Handling, the agent should verify the implementation against the acceptance criteria — not just check whether someone moved a Jira ticket to &quot;Done.&quot;</p><p>A ticket might be closed because:</p><ul><li>The feature was actually implemented correctly</li><li>Someone clicked &quot;Done&quot; by mistake</li><li>The scope was reduced without updating the spec</li><li>The implementation was partial but &quot;good enough&quot; for the sprint</li></ul><p>Specwright&#39;s agent reads the code and evaluates whether each acceptance criterion is actually satisfied, with evidence (file paths, line numbers, PR references).</p><h2 id="spec-realization" tabindex="-1">Spec Realization <a class="header-anchor" href="#spec-realization" aria-label="Permalink to &quot;Spec Realization&quot;">​</a></h2><p>This is what separates Specwright from spec management tools. The agent doesn&#39;t just track whether tickets are closed — it evaluates whether <strong>code actually implements what the spec says</strong>.</p><h3 id="how-it-works" tabindex="-1">How It Works <a class="header-anchor" href="#how-it-works" aria-label="Permalink to &quot;How It Works&quot;">​</a></h3><ol><li><strong>PR opens</strong> — Agent loads all indexed docs + specs relevant to the changed files</li><li><strong>Code analysis</strong> — Agent reads the diff and evaluates it against spec acceptance criteria</li><li><strong>Realization assessment</strong> — For each spec section: <ul><li><strong>Realized</strong>: Code implements the requirement (with evidence: file, line, PR)</li><li><strong>Partially realized</strong>: Some but not all acceptance criteria met</li><li><strong>Conflicting</strong>: Code contradicts the spec (suggests updating spec or code)</li><li><strong>Unrelated</strong>: PR doesn&#39;t touch this spec area</li></ul></li><li><strong>Auto-transition</strong> — When all AC in a section are realized, spec status moves to <code>done</code> and the linked ticket is closed</li><li><strong>Evidence trail</strong> — The agent records which PRs and code locations realize each section</li></ol><h3 id="what-the-engineer-sees" tabindex="-1">What the Engineer Sees <a class="header-anchor" href="#what-the-engineer-sees" aria-label="Permalink to &quot;What the Engineer Sees&quot;">​</a></h3><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>Spec Context</span></span>
<span class="line"><span></span></span>
<span class="line"><span>This PR relates to:</span></span>
<span class="line"><span>  payments-overhaul.md §3.2 (Retry Handling) — PAY-144</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Realization:</span></span>
<span class="line"><span>  ✅ AC1: Exponential backoff — implemented (src/payments/retry.ts:42)</span></span>
<span class="line"><span>  ⚠️ AC2: Max 3 retries — code uses max 5. Update spec or code?</span></span>
<span class="line"><span>  ⬜ AC3: Preserve idempotency key — not addressed in this PR</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Other docs affected:</span></span>
<span class="line"><span>  README.md §Error Handling — missing PaymentTimeoutError</span></span>
<span class="line"><span>  docs/architecture.md §Retry — references &quot;3 retries&quot;, now stale</span></span>
<span class="line"><span></span></span>
<span class="line"><span>[Update spec] [Create doc PR] [Dismiss]</span></span></code></pre></div><p>Not a wall of noise. Contextual, actionable, dismissible.</p><h2 id="replacing-confluence" tabindex="-1">Replacing Confluence <a class="header-anchor" href="#replacing-confluence" aria-label="Permalink to &quot;Replacing Confluence&quot;">​</a></h2><p>Every &quot;Confluence replacement&quot; pitch starts with &quot;import your wiki.&quot; That&#39;s wrong. You&#39;re importing a graveyard.</p><p>The adoption path is gradual:</p><ol><li><strong>Shadow mode</strong> (Month 1-2) — Install on 5-10 repos. New features get spec files instead of Confluence pages. Confluence stays as-is.</li><li><strong>Gravity shift</strong> (Month 3-4) — Engineers ask Specwright instead of searching Confluence. PMs notice their specs auto-update when code ships.</li><li><strong>The flip</strong> (Month 5-6) — &quot;Just update the spec&quot; replaces &quot;update the Confluence page.&quot; Confluence becomes read-only archive.</li></ol><p>You don&#39;t migrate content. You migrate <em>workflows</em>. When the workflow lives in Specwright, the content follows naturally. And because Specwright verifies docs against code, the content stays accurate — which is why Confluence failed in the first place.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><strong>Concept</strong>: <a href="/docs/concepts/coverage.html">Spec Coverage</a> — how realization is measured and tracked</li><li><strong>Concept</strong>: <a href="/docs/concepts/agent-mesh.html">Agent Mesh</a> — architecture of the agents that power living specs</li><li><strong>Concept</strong>: <a href="/docs/concepts/delta-tracking.html">Delta Tracking</a> — how status transitions and evidence are recorded</li><li><strong>Guide</strong>: <a href="/docs/guides/ticket-sync.html">Ticket Sync</a> — configuring bidirectional sync with Jira, Linear, GitHub Issues</li><li><strong>Reference</strong>: <a href="/docs/reference/cli.html">CLI</a> — <code>specwright verify</code> and <code>specwright audit</code> commands</li><li><strong>Reference</strong>: <a href="/docs/reference/skills.html">Claude Code Skills</a> — <code>/sw:verify</code>, <code>/sw:audit</code> for agent-assisted verification</li></ul>`,24)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};
