Stage

Overview

Stage is a serialization document for a round of engineering changes — it does not replace any skill output, but records what each skill produced, how those outputs relate to each other, and the complete story of this round of changes.

Stage answers four questions:

What were we supposed to do? (MISSION + normative documents)
How was the implementation safely delegated? (Task Contract forward index)
What did we actually achieve? (descriptive documents + ADR)
Why the difference? (normative vs. descriptive differences + learning summary)

                          STAGE.md
                   (Serialization layer / Index + narrative)
                          │
    ┌────────┬────────┬────┴────┬────────────┬────────┬────────┐
    │        │             │    │            │        │        │
  MISSION   Normative    Plan    Task Contract  Descriptive  Verification
  (Goal)    (Design)    (plan+todo) (Delegation boundary) (Result) (Evidence)
                                                │
                                              ADR
                                      (Mandatory, at least one per Stage)

When to Use

Stage creation is entirely user-driven. It is only created upon explicit user request, with no automatic triggers.

Users typically initiate it through:

"Create a Stage" / "Start a Stage"
"Create a Stage for this round of work"
"Seal the Stage" / "Close the Stage"
After /plan outputs a plan, the user replies "yes" to "Do you need a Stage document?"

Typical suitable scenarios (for user reference, not trigger rules):

Changes that span multiple tasks but form a logical whole
New features spanning multiple modules
Refactoring that changes internal structure but preserves behavior
A complete fix chain for a production defect
Any change that requires recording architecture decisions

Will NOT automatically trigger:

A single isolated task or mechanical change does not automatically create a Stage
Pure documentation updates do not automatically create a Stage
The Agent will not self-judge based on task count or cross-module extent — user confirmation is required

Even when delegated-task-contract needs its parent Stage, it must NOT automatically trigger Stage creation; if no Stage exists, it must pause and ask the user to explicitly decide. Directory membership, forward indexing, status synchronization, and sealing gates uniformly follow Stage and Task Contract Integration Rules.

Stage Types

Type	Motivation	Success Criteria	Normative vs. Descriptive	Documentation Focus
feat	Add new capability	New behavior appears and conforms to spec	Differences are expected; must be documented	spec + api-contract + api-doc
opt	Improve existing behavior	Metrics reach target values	Briefly document optimization results comparison	Performance baseline + optimization results
debug	Fix incorrect behavior	Issue no longer reproduces + regression tests cover root cause path	Normative = Descriptive (fix is the goal)	Phenomenon + Root cause + Fix strategy + Prevention
refactor	Change internal structure, preserve behavior	All existing behavior preserved, regression tests all green	Normative = Descriptive is a hard requirement	Architecture design + Structural change description

Stage Lifecycle

After /plan output         During implementation          After all implementation      During /ship execution
     │                          │                            │                      │
     ▼                          ▼                            ▼                      ▼
  Create skeleton           Maintain docs & Contract index  Seal STAGE.md           Check Stage existence
  (MISSION +                (Status, deviation, evidence  (Final gate, descriptive   (pre-launch
   normative doc paths,     summary)                       docs, ADR,               checklist
   implementation plan                                      difference analysis,     blocking items)
   links)                                                   verification results,
                                                             learning summary)

Creation (Skeleton Phase)

After /plan outputs tasks/plan.md and tasks/todo.md, the Agent asks the user if a Stage document is needed. Upon user confirmation:

Create directory stages/<stage-id>/ (stage-id is a kebab-case short title)
Create STAGE.md skeleton, pre-filled with:
- Type (feat | opt | debug | refactor)
- Status set to draft
- Decision maker
- MISSION (extracted from spec)
- Normative document paths (marked as TODO)
- Implementation plan links (fill with tasks/plan.md and tasks/todo.md)
- Task Contracts forward index table (initially empty)
- Descriptive documents (marked as TODO — filled after implementation completion)
- ADR (marked as TODO — at least one per Stage, filled after implementation completion)
- Verification results (marked as TODO)
Append a row to stages/INDEX.md

Population (Build Phase)

During implementation:

Ordinary task completion does not require modifying STAGE.md; however, Contract first write, status change, or return of deviation/evidence must be synchronized
When normative documents (spec, api-contract) are produced, update the corresponding links, removing TODO markers
Contracts are only forward-indexed by STAGE.md; do not add Stage fields or back-links in Contracts
Non-none Contract deviations are synchronized into the "Normative vs. Descriptive Differences" table immediately, rather than waiting until sealing to write from memory

Sealing (After Completion)

Once all tasks are completed and verified, the Agent reminds the user to seal. Upon user confirmation:

Review task-contract/ against the index table to ensure no omissions, dead links, or status drift
Confirm all Contract body statuses are COMPLETED or CANCELLED; any DRAFT, READY, or BLOCKED_BY_ARCHITECTURE will block sealing
Fill descriptive document links (api-doc, ADR)
Fill the Normative vs. Descriptive Differences Table (including a "Backport normative document?" column), incorporating meaningful deviations from Contract reports
Fill verification results and link Contract Required Evidence
Extract Learning Summary ("Do this next time" and "Don't do this next time")
Change status to done
Update the corresponding row status in stages/INDEX.md

Check (Pre-Launch)

The /ship pre-launch checklist includes:

"□ Do significant changes have a corresponding Stage document?" — If a Stage was created for this round of work, this is a blocking item

Stage Template

Below is the canonical template for stages/<stage-id>/STAGE.md:

# Stage: [Short Title]

**Type**: feat | opt | debug | refactor
**Date**: YYYY-MM-DD — YYYY-MM-DD
**Status**: draft | in-progress | done | abandoned | superseded | split
**Decision Maker**: @username

---

## MISSION (Goal for This Round)

<!-- feat / opt / refactor use standard MISSION -->

- **Objective**: [One sentence describing what to achieve in this round]
- **Users**: [Who will benefit]
- **Success Criteria**: [How to know it's done — specific, verifiable conditions]
- **Constraints**: [Binding limitations — technical, resource, time]
- **Out of Scope**: [Explicitly excluded items and reasons]

<!-- debug type replaces with the following structure: -->
<!--
- **Phenomenon**: [What the user did, saw, and should have seen]
- **Impact**: [Scope, duration, data integrity risk]
- **Root Cause Hypothesis**: [Initial assessment — update to confirmed root cause after implementation]
- **Fix Strategy**: [Stopgap + Root cause fix + Prevention]
- **Success Criteria**: [Issue no longer reproduces, regression tests cover root cause path, static checks for similar issues]
-->

→ See [MISSION.md](./MISSION.md)

---

## Normative Documents (Our Plan)

| Document | Source Skill | Description |
|----------|--------------|-------------|
| [spec/xxx.md](./spec/xxx.md) | spec-driven-dev | Functional specification |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | API contract |
| [design/xxx.md](./design/xxx.md) | — | [Supplementary description] |

> Filled before implementation starts. If a document type is not relevant to this round, delete the corresponding row.

---

## Implementation Plan

| Document | Source Skill | Description |
|----------|--------------|-------------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | Technical solution |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | Atomic task list |

---

## Task Contracts (Delegated Execution Boundaries)

> Only indexes writable delegations that require `delegated-task-contract` gates. Contract body, status, and Required Evidence are authoritative in the corresponding file; this table holds only forward links and summaries. Do not write Stage back-links into Contracts.

| Task | Contract | Status | Deviation / Evidence |
|------|----------|--------|----------------------|
| [Task ID] | [Task ID](./task-contract/TASK-XXX.md) | DRAFT \| READY \| BLOCKED_BY_ARCHITECTURE \| COMPLETED \| CANCELLED | [Blocking, deviation, evidence, or cancel reason; write `—` if none] |

> Keep the table header and delete example rows if no Contracts exist yet. Synchronize this table whenever a Contract is first written and on every status, deviation, or evidence change.

---

## Descriptive Documents (What We Actually Built)

> Filled after implementation completion.

| Document | Source Skill | Description |
|----------|--------------|-------------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | Actual API documentation |
| [docs/adr/XXX-title.md](./docs/adr/XXX-title.md) | documentation-and-adrs | Architecture Decision Record (required, at least one per Stage) |

### ADR (Required)

Each Stage **must** produce at least one ADR. ADRs record key architecture decisions and their context.

| ADR | Decision Content | Alternatives |
|-----|-----------------|-------------|
| [ADR-XXX](./docs/adr/XXX.md) | [One-sentence description of the decision] | [Rejected options and reasons] |

**ADR Content Requirements:**
- Record "why A was chosen over B"
- List considered and rejected alternatives with rejection reasons
- Describe constraints and consequences of the decision
- If the decision relates to an existing ADR, reference it explicitly

**ADR Focus for Different Stage Types:**

| Stage Type | Typical ADR Content |
|------------|---------------------|
| **feat** | Why this architecture/framework/protocol was chosen; data model design trade-offs |
| **opt** | Why this optimization strategy was chosen; why other options were not selected (e.g., caching vs. index optimization) |
| **debug** | Why the root cause existed; why this fix was chosen; prevention design |
| **refactor** | Why this new structure was chosen; why certain edge cases were not unified; comparison of old vs. new structure |

---

## Normative vs. Descriptive Differences

> Filled after implementation completion. Record every meaningful deviation between plan and reality.

When a Contract's `Required Evidence` report contains a non-`none` deviation, synchronize that deviation into this table upon acceptance of the Contract; do not leave the trace only in the Contract.

| Difference | Normative (Plan) | Descriptive (Result) | Reason | Backport Normative Document? |
|------------|------------------|----------------------|--------|------------------------------|
| [Brief description] | [How it was planned] | [How it was actually done] | [Why the deviation] | Yes / No |

**"Backport Normative Document?" Column Notes:**
- **Yes**: The deviation is deemed a correct design direction; the spec or api-contract has been retroactively updated to match the descriptive outcome
- **No**: The deviation is a temporary compromise or trade-off; the normative documents remain as-is for reference in subsequent Stages
- All rows marked "No" are candidate inputs for the next round's backlog

---

## Verification Results

| Check Item | Status | Evidence |
|------------|--------|----------|
| [Acceptance criterion 1] | ✅ / ❌ | [Test report, performance data, screenshot, etc.] |
| [Acceptance criterion 2] | ✅ / ❌ | [Evidence] |
| No regression | ✅ / ❌ | CI run link |

→ See [VERIFY.md](./VERIFY.md)

---

## Learning Summary

> Filled at sealing time. No more than two sentences.

- **Do this next time**: [What was done right this round — worth reusing in other Stages]
- **Don't do this next time**: [What went wrong this round — should be avoided, watched for, or improved]

---

## Related

- **Previous Stage**: [STAGE-XXX](../stage-XXX/STAGE.md) (or "None")
- **Next Round Plan**: [Brief description, or "None"]

Increments (Post-Sealing Additions)

After a Stage is sealed (status becomes done), if minor issues need patching but do not constitute a new Stage, an increment section may be appended at the end of STAGE.md:

---

## Increment 1 (2026-07-28)

- **Change**: [Brief description of what was patched]
- **Reason**: [Why this patch was needed after sealing]
- **Scope**: [Which files/modules]

When appending increments:

Stage status remains done, not reverted to in-progress
Increment entries are appended in chronological order
If the patch involves a new ADR decision, append it to the descriptive ADR table and annotate with [Increment 1]
When there are 3 or more increments total, consider whether a new Stage should be created instead of continuing to append

INDEX.md

stages/INDEX.md is the navigation entry point for all Stages. It is maintained when each Stage is created and sealed.

# Stage Index

| ID | Title | Type | Status | Affected Modules | Date |
|----|-------|------|--------|------------------|------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |

Maintenance Rules:

Append a row with status draft when a Stage is created
Update status to done when a Stage is sealed
Synchronize when a Stage's status changes to abandoned, superseded, or split
Affected Modules lists the top-level modules/directories impacted, for module-based searching

Status Model

Status	Meaning	When to Use
`draft`	Skeleton created, implementation not yet started	After Stage creation
`in-progress`	Implementation in progress	During implementation (optional)
`done`	Completed as planned, sealed	All tasks completed, verified, learning summary written
`abandoned`	Abandoned mid-course	Direction was wrong, requirements canceled, interrupted by higher priority
`superseded`	Superseded by another Stage	Stage-B's scope consumed Stage-A
`split`	Split into multiple smaller Stages	Stage was too large, split into independent sub-Stages

Handling abandoned:

Update the MISSION section, appending a paragraph on "Reason for abandonment"
Keep at least one ADR in the ADR table, recording "Why it was not continued"
Fill out the learning summary as usual — lessons from abandonment are often more valuable than those from success
Whether to roll back completed code/documentation in the abandoned Stage is decided by the decision maker and recorded in the ADR
Change the "Next Round Plan" in the Related section to "None (abandoned)"

Handling superseded:

Update the MISSION section, appending a paragraph on "Which Stage superseded it and why"
Add a line to the Related section: "Superseded by: STAGE-XXX"
Change status to superseded
Do not continue appending increments to the superseded Stage — all subsequent work moves to the superseding Stage

Handling split:

Update the MISSION section, appending a paragraph on "Which sub-Stages it was split into and why"
Add a line to the Related section: "Split into: STAGE-XXX, STAGE-YYY"
Change status to split
The original Stage no longer receives increments — all work moves to the sub-Stages

Directory Structure

stages/
  INDEX.md                      ← Index, one row per Stage
  001-raft-election-optimization/
    STAGE.md                    ← Stage serialization document
    MISSION.md                  ← Detailed goal description (optional, recommended for complex projects)
    spec/                       ← Normative: functional specification
    design/                     ← Normative: protocol contracts, data layout
    tasks/
      plan.md                   ← Implementation plan
      todo.md                   ← Task list
    task-contract/              ← Delegated execution boundaries, same level as tasks/spec
      TASK-001.md
      TASK-002.md
    docs/
      protocol/                 ← Descriptive: protocol documents, RPC interfaces
      adr/                      ← Descriptive: Architecture Decision Records (required)
    verify/                     ← Verification evidence
      fault-injection-report.md
      consistency-check.txt
      perf-before-after.json
  002-wal-checksum/
    ...
    ...

Except for the membership path of Task Contracts, the directory structure is a recommended pattern. The core constraints are: STAGE.md must exist, each Stage must contain at least one ADR; if Task Contracts exist, they must reside under the Stage's task-contract/ directory and be forward-indexed by STAGE.md.

Interaction with Other Skills

Skill	Interaction Method
spec-driven-development	Stage's MISSION is extracted from the spec's Objective
planning-and-task-breakdown	After `/plan` output, Agent asks whether to create a Stage skeleton
delegated-task-contract	Contract is saved to the current Stage's `task-contract/`; `STAGE.md` forward-indexes its status, deviation, and evidence; Contract does NOT back-index the Stage
api-and-interface-design	Both protocol contracts (gRPC/protobuf) in normative documents and interface documents in descriptive documents are linked to the Stage
failure-injection-testing	When fault tolerance and recovery are involved, fault injection plans and chaos experiment reports are linked to the Stage's descriptive documents
consistency-and-durability-verification	When storage or state replication is involved, consistency/durability verification reports are linked to the Stage's verification results
agent-native implementation flow	After all tasks are completed and verified, the Agent reminds to seal the Stage
documentation-and-adrs	ADR is a mandatory output of the Stage; each Stage requires at least one
shipping-and-launch	`/ship` checks whether a Stage exists (blocks if one was created for this round)

Common Rationalization Excuses

Rationalization Excuse	Reality
"This round of changes is too small, no Stage needed"	If the change is too small to need a Stage, it probably doesn't need an ADR either. But the user has already decided to create a Stage — trust the user's judgment.
"The requirements are too simple, there won't be any differences between normative and descriptive"	Differences exist everywhere — even the simplest change may deviate from the plan during implementation. The core value of Stage is precisely to record these differences.
"Let's write the code first, I'll fill in the Stage later"	Before sealing, the Stage is a living directory, not needing to be written all at once. But writing after the fact means difference analysis relies on memory — and memory is unreliable.
"This doesn't need an ADR"	Every Stage has at least one decision worth recording — even if it's just "We chose the simplest implementation because current constraints don't allow a more complex approach."
"It's already `abandoned`, the learning summary is meaningless"	Lessons from abandonment are often more valuable than those from success. Recording "why it was abandoned" is at least as important as recording "why it succeeded."
"Marking 'No' in the difference table is enough, no explanation needed"	Every row in the difference table is an input for future decisions. A row marked "No" tells the next person "There's technical debt here, and it was left intentionally."
"INDEX.md can be filled in later"	The value of INDEX.md grows with the number of Stages — you might not notice it with the first one, but by the tenth it's indispensable. Maintain it from the start.

Red Flags

STAGE.md is created but MISSION is empty — the skeleton's value is in the MISSION; a Stage without a goal is just a placeholder
Descriptive documents include API docs but no corresponding ADR — violates the "at least one ADR per Stage" rule
Difference table is empty but the user mentioned deviations during implementation — differences were not captured
Learning summary says "None" or "Everything went smoothly" — every Stage has lessons; if you can't find any, reflection wasn't deep enough
An abandoned Stage lacks "Reason for abandonment" — the most valuable information is lost
A row in INDEX.md has been in draft status for a long time — either push forward with implementation or mark it as abandoned; don't let the skeleton rot
Increment section has 3+ entries but splitting into a new Stage has not been considered — indicates the scope judgment was flawed; reflect rather than continue appending
Decision Maker field is empty — in multi-person collaboration, this breaks the decision traceability chain
Files exist in task-contract/ that are not indexed by STAGE.md, or indexed links point to non-existent Contracts
Contract status, deviation, or evidence has changed but the Stage table still contains the old summary
Contract back-links to STAGE.md, causing the membership to be maintained bidirectionally
Stage is marked as done while there are still contracts in DRAFT, READY, or BLOCKED_BY_ARCHITECTURE status

Verification

After creating a Stage skeleton:

stages/<stage-id>/STAGE.md exists
Stage type (feat | opt | debug | refactor) is filled
Status is draft
Decision maker is filled
MISSION is filled (standard format or debug format, depending on type)
Implementation plan links point to tasks/plan.md and tasks/todo.md
The "Task Contracts (Delegated Execution Boundaries)" section and empty forward index table are created
Corresponding row appended to stages/INDEX.md

After sealing a Stage:

13eholder/zflow

What is zflow?

Ask in your favorite AI

Documentation