Guide / Methodology
Give the next developer or coding agent a reliable answer to three questions:
A developer should not have to reverse-engineer the whole app to find out what is already built.
The Epic says what the product does. Its evidence points to the code and tests. If those disagree, that is work to fix.01 / Problem
AI coding agents can build quickly. Coming back a week later and figuring out what they actually built is still harder than it should be.
The annoying part comes later.
A ticket captures a plan. A pull request captures one slice of history. Both can be useful, but neither is a dependable map of the current application.
Then the edge cases show up. The data model shifts. Review finds a better approach. A few patches later, the plan and the code no longer agree, and answering a basic question means reading half the repo.
The first hour disappears into routes, services, stale layers, and tests that may prove the wrong thing.
The agent burns context and tokens reading half the repo before it can do useful work. That is a weak place to start.
02 / Model
I keep the product's accepted behavior separate from the Change used to modify it. The plan can move when implementation reality shows up. The end state, code ownership, and proof cannot quietly disappear.
Behavior
Explain what the user or operator can do and why it matters. They are durable current-state records: when that behavior changes, the Story changes with it.
Contract
Spell out the rules and observable examples that make “done” testable.
Ownership
Point the next developer at the routes, services, components, and other code that actually owns the behavior.
Proof
Name the tests, checks, or manual scenarios that prove the behavior. “The build passed” is not enough.
Durable behavior, temporary work
Stories are not tasks that expire after implementation. When accepted behavior evolves, update the existing Story, its Requirements and Scenarios, and its implementation and evidence maps to describe what is true now. Create a new Story only for a genuinely distinct, durable user outcome. Once the work is finished, the Change becomes history; the updated Story remains.
Three records, three jobs
A PRD can guide the product for years. A Change becomes history as soon as the work is done. An Epic has to keep changing with the application. Asking one document to do all three jobs is how the docs stop being useful.
01 / Planning
Planning holds product direction, exploration, open questions, and possible work. It describes the intent and constraints before the team has committed to a delivery path.
It can change or be abandoned without claiming that the product itself changed.
02 / Project
Project records describe the system as it exists. Epics map accepted behavior to implementation and evidence. ADRs preserve durable decisions. Supporting docs explain the system around them.
When behavior changes, its existing Story changes with it. These records are current truth, not completed tasks or snapshots of the original plan.
03 / Changes
A Change is the working record for one bounded move. It keeps the scope, intended end state, decisions, work status, and verification together while implementation is still moving.
When delivery ends, it becomes history. Any durable result is reconciled into the project records.
Planning gives a Change its purpose. The Change guides the move. Project records are reconciled to what actually shipped, then the Change becomes history.
03 / Workflow
The method does not depend on Markdown, a CLI, a particular tracker, or an agent runtime. What matters is preserving the same outcome at each stage.
Work through the product or technical question before turning it into a build plan.
Write down what should change. Save the technical plan until the work is close enough to begin.
Revisit the current code, then tighten the Stories, Requirements, Scenarios, technical choices, and verification.
If the work has a UI, settle the flow, responsive behavior, states, accessibility, and visual direction.
Put the implementation-ready plan where the people and systems doing the work can find it.
Build one Requirement at a time, prefer BDD/TDD, and keep the Epic current as the implementation changes.
Read the whole diff. Follow the affected callers and contracts, use the configured analyzers, and keep manual acceptance as a separate gate.
Update the existing Stories and their behavior maps to match what shipped. Add a Story only for a distinct durable outcome. Keep unresolved gaps visible, verify the exact delivery diff, then follow the team's release policy.
04 / Traceability
An ID is useful only if it leads from a behavior to the code that owns it and the evidence that proves it.
LC-001
LC-001/S2
R2
R2-S1
05 / Example
This fictional note-saving capability has one Story and one Requirement. It shows the full path from product intent to code ownership and proof without burying the shape in a large example.
Illustrative Epic / LC-001 Saved Notes
Rendered for readability
NotesPersistence overviewADR-0003 Durable note storageWriters need their work to survive refreshes and later sessions without wondering whether the last edit reached durable storage.
Signed-in writers can save a valid note and load the same content later. A failed save leaves their draft intact and explains what happened.
None. Future ideas remain outside accepted Story truth until promoted.
| Story | Implementation | Verification | Capability | Last Verified | Notes |
|---|---|---|---|---|---|
S1 |
implemented | verified | Save a note. | 2026-07-22 |
Implementation: implemented
Verification:
verified
Created: 2026-07-01
Modified: 2026-07-22
Last
verified: 2026-07-22
As a writer, I want to save my note, so that I can return to the same work later.
Requirement R1: Durable save
The application SHALL persist valid note content for the signed-in writer and preserve the current draft when persistence fails.
Scenario R1-S1: Save and reload
Scenario R1-S2: Persistence rejects the save
| Requirement / Scenario | Location / Anchor | Kind | Responsibility |
|---|---|---|---|
S1/R1 |
src/notes/save-note.ts#saveNote |
primary | Owns validation, persistence, and the returned save state. |
S1/R1-S2 |
src/notes/editor.ts#handleSaveFailure |
support | Preserves the active draft and presents the retryable failure. |
| Requirement / Scenario | Evidence | Proves | Status |
|---|---|---|---|
S1/R1-S1 |
Automated test test/notes/save-note.test.ts#saves and reloads a note |
The persisted note is returned after a fresh load. | Passing 2026-07-22 |
S1/R1-S2 |
Automated test test/notes/save-note.test.ts#keeps edits when save fails |
An injected failure preserves content and exposes a retry. | Passing 2026-07-22 |
saveNote owns the save contract. The editor is supporting UI behavior, not a second
implementation owner.This Epic is healthy when:
Real Epics will be bigger. The useful part stays the same: accepted behavior has an owner, observable Scenarios have proof or an explicit gap, and the document describes the application as it exists now.
Part 02 / Reference implementation
Everything above this line is the method. What follows is my current local-first implementation: Markdown artifacts, portable repository contracts, private user topology, a deterministic CLI, and agent skills.
06 / Package
The CLI owns structure, configuration, and deterministic state transitions. The skills handle the contextual work: planning, implementation, review, reconciliation, and release judgment.
Default filesystem layout
Planning stays idea-owned and private by default. Project truth and active work live with the code.
~/.sdd/config.yaml maps those private relationships, while each repository commits its own
portable .sdd/config.yaml.
01 / Planning
<planning-root>/<idea>/
prd.md
exploration/
planned-changes/Product direction, exploratory notes, Change Briefs, and planned Change drafts stay here until work is ready to enter a repository.
02 / Project
<repository>/docs/
epics/<epic>/epic.md
adrs/<date>-<decision>.md
audits/Epics hold durable behavior and evidence maps. ADRs keep lasting decisions. Audits remain point-in-time advisory records.
03 / Changes
<repository>/docs/changes/
<date>-<change>/
proposal.md
design.md
tasks.md
closed/Promotion moves a planned Change here. Closeout moves it under
docs/changes/closed/ after project truth has been reconciled.
Two layers share the work
Method to package
The commands below are conveniences provided by this package. They implement the stages above; they do not define the methodology.
/sdd-explore/sdd-change --brief/sdd-change --plan/sdd-design --plansdd change promote/sdd-apply/sdd-review/sdd-epic-verify/sdd-pr/sdd-releaseOptional component lifecycle
A shared catalog can incubate reusable patterns without turning them into mandatory application dependencies.
An application can still keep its own component or deliberately diverge. That is a valid outcome.
$ git clone https://github.com/TaylorHuston/sdd-skills.git
$ cd sdd-skills
$ npm install
$ npm link
$ sdd setup
$ cd /path/to/repository
$ sdd init
$ sdd doctorPre-1.0 distribution: install from the GitHub checkout for now. A standard npm registry install is targeted for the 1.0 release. See what changed
The North Star
That is the whole point. If the docs say one thing and the code does another, fix the disagreement. The next developer should know where to begin.
Continue to the repository documentation