WRIT Docs

#Specification Process

All non-trivial changes in WRIT begin with a specification. This page describes the spec lifecycle, from initial draft through implementation to delivery.

#Why Specifications?

Specifications serve three purposes:

  1. Alignment — They ensure the human operator and the implementing agent agree on what will be built before any code is written.
  2. Auditability — They provide a record of decisions, trade-offs, and rationale that future contributors can reference.
  3. Scope control — They prevent scope creep by defining explicit items and acceptance criteria.

#Spec Lifecycle

Every specification moves through these statuses:

Status Meaning
draft Being written. Open questions may remain. Not ready for implementation.
ready All questions resolved. Items and acceptance criteria are complete. Ready to be picked up by a Sole Implementor.
in_progress A Sole Implementor is actively working on the spec. Progress log is being updated.
delivered All items implemented, audit rounds complete, code merged.
blocked Implementation cannot proceed due to an external dependency or unresolved issue.
archived Superseded or abandoned. Kept for historical reference.

#Spec Format

Specifications live in /docs/specs/ and follow a consistent structure:

# Specification: <Title>

| Field    | Value     |
|----------|-----------|
| Status   | draft     |
| Priority | P1/P2/P3  |
| Created  | YYYY-MM-DD|
| Authors  | ...       |

## Goal
One paragraph explaining what this spec achieves.

## Background
Context: why this is needed, what problem it solves.

## Decisions
Numbered decisions with rationale.

## Items
Checkbox list of implementation items.

## Implementation Sequence
Phases with gate criteria.

## Open Questions
Questions that need resolution before status can move to ready.

## Progress Log
Timestamps of phase starts and completions.

## Audit Rounds
Results of the three audit rounds.

## Session Notes
Handoff notes between sessions.

#Writing a Spec

Specs are typically authored in a session where the human operator works with Claude in the Specification Generator role:

  1. The human describes the need or problem.
  2. Claude drafts the spec, asking clarifying questions.
  3. The human reviews, iterates, and resolves open questions.
  4. When all questions are resolved, the status moves to ready.

#Implementing a Spec

When a spec is ready, the human assigns a Sole Implementor session:

  1. The implementor reads the spec and follows the implementation sequence.
  2. Each phase is completed before advancing to the next.
  3. Progress is logged in the spec's Progress Log section.
  4. After all items are complete, three audit rounds verify quality.
  5. On successful audit, the spec status moves to delivered.

#Audit Rounds

Three rounds of review ensure quality:

  1. Round 1 — Full review against the spec items, engineering guidelines, and design guidelines. Issues found are fixed.
  2. Round 2 — Re-review of round 1 fixes plus any areas that were not fully checked.
  3. Round 3 — Final pass. If no issues are found, the spec is delivered.

#See Also