Sample fixture
Sample: Document-Aware Development
A sample fixture for testing how decisions, specifications, tasks, and code relate in the English content model.
Sample fixture.This article is sample content for reviewing the bilingual reading experience. It makes no claim about the author’s work or views.
This is a sample fixture. It makes no claim about the author’s experience or personal views.
Begin with the decision
A code change is easier to review when the reason for it is visible. In this sample workflow, an accepted decision becomes a testable specification before it becomes an implementation task. The chain is deliberately short: ADR → SPEC → TASK → CODE.
The point is not to produce more documents. It is to keep the constraint that shaped a change close enough to the change that a reviewer can test whether the two still agree.
Keep the contract executable
A specification should name an observable outcome. The task can then select the smallest change that proves that outcome, while evidence records what actually happened.
type Stage = 'adr' | 'spec' | 'task' | 'code';
const trace = (stages: Stage[]) =>
stages.every((stage, index) => index === 0 || stage !== stages[index - 1]);Isolate technical identifiers
Commands such as npm run check, identifiers such as translationKey, and a URL such as https://example.com/system-boundary retain their left-to-right direction even when the surrounding edition uses another writing direction.
Move through explicit states
The workflow is useful when each transition has a clear owner and a visible test. A draft task cannot silently override an accepted decision, and a completed task cannot rely on evidence that was never captured.
| Stage | Question | Evidence |
|---|---|---|
| ADR | Why this direction? | Accepted decision |
| SPEC | What must be observable? | Testable criteria |
| TASK | What is the smallest change? | Commands and captures |
Review the distance
The practical risk is distance: a decision in one place, a task in another, and a test with no visible relationship to either. A small traceability record reduces that distance without pretending that documentation can replace judgment.1
The review question stays simple: can another person follow the reason, the contract, the change, and the evidence without reconstructing the entire project history?
- This note is fixture content used to verify footnote rhythm and keyboard navigation. ↩