Board Format Specification

The .absolute-work/board.md file is the single source of truth for an Absolute Work run. It is the only state — fully local, no external trackers — and is designed to be both human-readable and machine-parseable. It survives across sessions to enable resume, audit, and handoff.

File Location

{project-root}/.absolute-work/board.md

The .absolute-work/ directory may also contain:

• board.md — the main board (always present)
• archive/board-{timestamp}.md — completed or superseded boards

The user chooses during intake whether .absolute-work/ is git-tracked (audit trail, resume across machines) or gitignored (local working state).

Board Metadata (YAML frontmatter)

---
id: aw-{timestamp}
title: "{brief description of the overall task}"
type: feature | bug | refactor | greenfield | planning | migration
status: intake | spec | decomposing | planning | executing | verifying | converged | completed | abandoned
created: "{ISO 8601}"
updated: "{ISO 8601}"
git_tracked: true | false
evaluator_enabled: true | false
total_tasks: {N}
completed_tasks: {N}
failed_tasks: {N}
current_wave: {N}
total_waves: {N}
---

evaluator_enabled defaults to true for boards with any M-size tasks; set false only when all tasks are S-size.

Board Sections

1. Intake Summary

## Intake Summary
- **Task**: {one-line description}
- **Type**: feature | bug | refactor | greenfield | planning | migration
- **Complexity**: simple | medium | complex
- **Problem**: {what needs to be built/fixed}
- **Success Criteria**: {what "done" looks like}
- **Constraints**: {patterns, libraries, conventions to follow}
- **Dependencies**: {external APIs, services, other work}
- **Edge Cases**: {known edge cases} (if complex)
- **Spec**: docs/plans/{date}-{topic}-design.md
- **Board Persistence**: git-tracked | gitignored

2. Project Conventions

Written during Codebase Convention Detection — package manager, language/runtime, test runner, linter/formatter, build system, available scripts, directory conventions. Referenced by every later phase and by every execution agent's prompt.

3. Task Graph

## Task Graph

### Sub-tasks
| ID | Title | Type | Size | Dependencies | Wave | Run | Status |
|----|-------|------|------|-------------|------|-----|--------|
| AW-001 | {title} | config | S | - | 1 | seq | done |
| AW-002 | {title} | code | M | AW-001 | 2 | seq | in-progress |
| AW-003 | {title} | code | S | AW-001 | 2 | parallel | pending |

### Dependency Graph
{ASCII graph — see execution-model.md}

### Wave Assignments
- **Wave 1** (1 task): AW-001 [sequential — blocker, shared file]
- **Wave 2** (2 tasks): AW-002 [sequential], AW-003 [parallel-safe]

The Run column records the safety decision: seq (blocker/dependent/shared-file → run in order) or parallel (disjoint files, no shared interfaces → may run concurrently).

4. Tasks (per-task detail)

## Tasks

### AW-001: {title}
- **Type**: code | test | docs | infra | config
- **Size**: S | M
- **Dependencies**: none | [AW-XXX]
- **Wave**: {N}  **Run**: seq | parallel
- **Status**: {current status}

#### Research Notes
- Key files: {list}
- Reusable code: {functions/utilities to reuse}
- Patterns: {conventions observed}
- Risks: {risks identified}

#### Execution Plan
- Files to create/modify: {list}
- Test files: {list}
- Approach: {brief}
- Acceptance criteria:
  - [ ] {criterion 1}
- Test cases: {happy path, edge, error}

#### Verification
- Signals: PASS | FAIL
- Tests: {passed}/{total} ({new} new)
- Lint: clean | {issues}   Type Check: pass | {errors}   Build: pass | fail
- Evaluator Score: {N.N}/5.0 | skipped (S-size)
- Verdict: PASS | NEEDS WORK | FAIL    Iteration: {N}/5

5. Rollback Point

## Rollback Point
- Pre-execution commit: {hash}
- Recorded: {timestamp}

6. Execution Log

## Execution Log
### Wave 1 — {timestamp}
- Tasks: AW-001 (seq)
- Completed: {timestamp} — Result: all passed

7. Deferred Work

## Deferred Work
- {non-blocking discovery}, found during {task}, not in original scope

8. Convergence Summary

## Convergence Summary
### Files Changed
| File | Action | Lines |
|------|--------|-------|
| src/api/auth.ts | created | +120 |

### Tests Added
- Total new tests: {N}    Coverage: {% if available}

### Key Decisions
- {decision and why}

### Suggested Commit Message
{emoji} {type}: {subject}

{body}

Status Transitions

Board-level

intake → spec → decomposing → planning → executing → verifying → converged → completed
                                                                      └→ abandoned

Task-level

pending → researching → planned → in-progress → verifying → done
                                      │             └→ failed (retry)
                                      └→ blocked

Resuming a Board

At the start of any invocation, if .absolute-work/board.md exists:

1. Read the board; parse frontmatter and current state.
2. Display a compact status summary.
3. Identify the current phase and incomplete tasks (anything not done/failed).
4. Resume from the current point — executing → next unfinished wave; verifying → re-run verification on unverified tasks; planning → finish remaining plans.
5. Add a "Resumed at {timestamp}" entry to the Execution Log.
6. Reconcile: if the codebase changed since updated, flag conflicts before continuing.

If the board is completed, ask whether to start fresh (archive to archive/board-{timestamp}.md) or review. Never overwrite a board without explicit confirmation.

Example Board (abbreviated)

---
id: aw-1717400000
title: "Add user authentication to Next.js app"
type: feature
status: executing
git_tracked: false
total_tasks: 8
completed_tasks: 3
current_wave: 2
total_waves: 4
---

## Intake Summary
- **Task**: Add email/password + Google OAuth authentication
- **Type**: feature  **Complexity**: complex
- **Constraints**: NextAuth.js v5, existing Prisma + PostgreSQL
- **Spec**: docs/plans/2026-06-03-auth-design.md
- **Board Persistence**: gitignored

## Task Graph
### Sub-tasks
| ID | Title | Type | Size | Dependencies | Wave | Run | Status |
|----|-------|------|------|-------------|------|-----|--------|
| AW-001 | NextAuth config + providers | config | S | - | 1 | seq | done |
| AW-002 | User + Account Prisma models | config | S | - | 1 | parallel | done |
| AW-003 | Auth API route handler | code | M | AW-001, AW-002 | 2 | seq | in-progress |
| AW-004 | Auth middleware | code | M | AW-001 | 2 | parallel | done |

### Wave Assignments
- **Wave 1** (2): AW-001 [seq — shared config], AW-002 [parallel-safe]
- **Wave 2** (2): AW-003 [seq], AW-004 [parallel-safe]

## Rollback Point
- Pre-execution commit: a1b2c3d

Execution Model

Absolute Work executes a dependency-graphed task board one safe wave at a time — the onion-peel. The defining rule is safety over speed: blockers and dependents run sequentially; only provably-independent tasks run in parallel. When in doubt, serialize.

Identifying Dependencies

Task B depends on task A if:

• B needs code/files that A creates
• B imports or uses a function/type/interface A defines
• B tests, extends, modifies, or documents A's output
• B configures infrastructure A requires

B does NOT depend on A if they modify different files with no shared interfaces and can be tested in isolation.

Dependency checklist (per task pair)

1. Does B need any file A creates? → dependency
2. Does B import any symbol A defines? → dependency
3. Does B test code A writes? → dependency
4. Can B's tests pass without A complete? → if yes, no dependency

Common DAG Patterns

Linear chain:   AW-001 → AW-002 → AW-003          (no parallelism; each task is a wave)
Fan-out:        AW-001 → {AW-002, AW-003, AW-004}  (W1: 001; W2: the rest)
Fan-in:         {AW-001, AW-002, AW-003} → AW-004  (W1: the three; W2: 004)
Diamond:        001 → {002, 003} → 004             (setup → parallel features → integration)
Independent clusters: A:001→002  B:003→004  C:005  (disconnected sub-graphs)
Layered:        infra → data → logic → ui → tests  (one wave per layer)

The Safety-First Wave Algorithm

Two passes: depth grouping, then a safety partition.

Pass 1 — Depth grouping (topological)

for each task:
  depth = 0 if no dependencies
          else max(dependency.depth) + 1
waves = group tasks by depth     // Wave 1 = depth 0, Wave 2 = depth 1, ...

Waves execute in strict serial order — Wave N+1 never starts until Wave N is fully verified and the user confirms.

Pass 2 — Safety partition (within each wave)

Classify every task in the wave as seq (sequential) or parallel:

A task is parallel-safe only if ALL hold:

• It touches a disjoint set of files from every other task in the wave
• It shares no interfaces/types being defined by another task in the wave
• It is not a blocker that a later task in the same wave reads from
• Its outcome does not change another task's plan

Otherwise it is seq — run it alone, in dependency order. Default to seq when uncertain. Record the decision in the board's Run column with a one-line reason.

Shared-file ownership

If two same-wave tasks would touch the same file, assign that file to one owner task; the others treat it as read-only until the owner completes, or get moved to a later wave. This is the single most common source of wave-boundary conflicts — resolve it at decomposition time.

Execution within a wave

run all `seq` tasks first, one at a time, in dependency order
then run `parallel`-safe tasks concurrently (separate agents)
wait for the whole wave to finish → wave boundary checks → GATE → next wave

Running seq tasks first means the riskiest/shared work lands before independent work fans out, so parallel agents build on a settled base.

Worktree isolation (optional)

On platforms that support it, run parallel tasks in isolated worktrees when there is any residual risk of file overlap; merge back at the wave boundary. Skip it when tasks touch clearly different directories — the merge overhead isn't worth it.

ASCII Graph Rendering

Task Graph:
  [W1] AW-001 [config: Init structure]           (seq — shared config)
         ├──> [W2] AW-002 [code: DB schema]        (seq)
         └──> [W2] AW-003 [code: API router]       (parallel-safe)

Wave Summary:
  Wave 1 (1): AW-001  [seq]
  Wave 2 (2): AW-002 [seq], AW-003 [parallel]

Pre-Execution Snapshot

Before any file is touched in Wave 1:

1. Ensure the working tree is clean (commit or stash existing changes).
2. Record the current commit hash on the board under ## Rollback Point.
3. If execution goes catastrophically wrong, the user can git reset --hard to this commit.

Record the hash before Wave 1 begins — a mid-wave snapshot already contains partial changes.

Agent Prompt Template

Each execution agent receives a self-contained prompt from the board:

## Task: {AW-XXX} - {Title}

### Context
{description from the board}

### Project Conventions
{detected conventions — package manager, test runner, linter, directory patterns}

### Research Notes
{key files, reusable code, patterns, risks for this task}

### Execution Plan
- Files to create/modify: {list}
- Test files: {list}
- Approach: {from PLAN}

### Acceptance Criteria
{specific, verifiable conditions}

### Rules
1. Write tests FIRST, watch them fail (red), then implement (green), then refactor.
2. Run lint and type-check on modified files via the project's scripts.
3. Do NOT modify files outside your task scope.
4. Reuse existing utilities named in the research notes — do not reinvent them.
5. If blocked, STOP and report the blocker — never work around it.
6. Report: files changed, tests written, tests passing, any issues.

Template by task type

• code → full TDD template above.
• test → skip "write tests first" (the task is the tests); write happy/edge/error cases and run against the implementation.
• docs → no TDD; follow existing doc style; verify code examples are syntactically valid.
• config/infra → verify by running the relevant tool/build; check idempotency.

Wave Boundary Checks

After every task in a wave completes, before the gate:

1. Conflict check — did any two agents modify the same file? Merge intelligently (prefer the change that better satisfies its acceptance criteria); if unmergeable, present both versions to the user.
2. Interface compatibility — types defined by one task match those expected by another.
3. Import resolution — all cross-task imports resolve.
4. Combined build + tests — run the build and the wave's tests together.
5. Progress report — print a compact status table:

Wave 2 complete (2/4 waves)
| Task   | Run      | Status | Notes |
|--------|----------|--------|-------|
| AW-003 | seq      | done   |       |
| AW-004 | parallel | done   |       |

Then GATE — confirm before starting the next wave.

Scope Creep Guard

• Blocking discovery (can't finish the current task without it): add a new visible task to the DAG, place it in the current or next wave, flag it on the board, continue with other tasks.
• Non-blocking discovery (nice-to-have, adjacent cleanup): do NOT absorb it. Add it to ## Deferred Work, mention it at CONVERGE. The user decides whether to start a new session.
• Never silently expand scope — every DAG addition is visible on the board and called out in the next progress report.

Blocked Tasks

When a task is blocked:
  1. Mark status `blocked` with a reason and the blocking task ID.
  2. Continue executing non-blocked tasks in the wave.
  3. After the wave, reassess:
     - blocker resolved → add to the next wave
     - blocker persists → flag for user attention
     - approachable differently → revise plan and retry

If a Wave N task fails and Wave N+1 tasks depend on it, mark the dependents blocked (not failed); run the non-dependent Wave N+1 tasks normally; unblock dependents if the failure is later fixed.

Failure Recovery

On retry, append the error to the agent prompt: "Previous attempt failed because: {error}. Fix and retry." When retries are exhausted, mark the task failed, record all attempt logs, flag the user with the rollback hash, and continue with non-dependent tasks. Never bypass tests or checks to force a pass.

Performance Guidelines

• Optimal wave size: 1-3 parallel tasks (low overhead); 4-6 (good throughput); 7+ → split into sub-waves to limit failure blast radius.
• Each parallel agent consumes context and compute; in constrained environments, cap concurrency at 3-4.
• Skip parallelism when a wave has one task, when all tasks touch the same file, or when any dependency isn't fully captured in the DAG (a sign the decomposition needs another pass).

Intake Playbook

The design interview is the engine of Absolute Work. A relentless, structured interview extracts every requirement, constraint, and edge case before a single line of code is written. This playbook covers design-tree traversal, adaptive question banks per work type, codebase-first intelligence, question calibration, implicit-requirement extraction, and anti-patterns.

Design Tree Traversal

Every unit of work is a tree of decisions. Walk it depth-first, resolving each branch completely before moving to siblings. This prevents half-explored requirements from haunting the implementation later.

Rules

1. Root first — start with purpose. Why does this exist? What problem does it solve?
2. Depth before breadth — explore the first child fully before siblings.
3. Resolve before advancing — a node is resolved when you have a clear answer, a concrete decision, or an explicit deferral. Never leave a node ambiguous.
4. Backtrack on dead ends — if a branch leads to "we don't need this," mark it explicitly out of scope and backtrack.
5. Dependency edges — if a node depends on another branch, resolve the blocker first.

Example tree: "Add a commenting system"

commenting-system
├── purpose (who comments? what is commentable?)
├── data-model (schema, threading flat vs nested, storage)
├── permissions (create/edit/delete, moderation)
├── ui (input, list, threading display, empty state)
├── real-time (needed? transport? optimistic updates?)
├── notifications (notify on reply? channel?)
└── edge-cases (deleted parent, deleted post, concurrent edits, spam)

By the time you reach notifications, the threading decision is already resolved, so you know whether replies even exist. Upstream decisions constrain downstream ones — always interview in tree order: purpose → data model → behavior → UI → edge cases.

Adaptive Question Banks by Work Type

Detect the work type, then use its bank. Scale depth to complexity (see Scaling Rules below).

Feature

Bug

Refactor

Greenfield

Planning / Breakdown

Use when the user wants a vague goal turned into a sequenced plan rather than an immediate build.

Migration

For migrations, also load migration-playbook.md — it covers call-site inventory, codemods, incremental rollout, and backwards-compatibility in depth.

Codebase-First Intelligence

Before asking the user a question, check whether the codebase already has the answer. Every question the codebase could have answered is a wasted round-trip that erodes trust.

Protocol

For every question you are about to ask:

1. Can I find it in the codebase? Search; if found, state it and skip the question.
2. Can I infer it? If the project uses Prisma + Postgres, don't ask "what database?" — state it and ask the deeper question.
3. Is this a fact or a preference? Facts live in code (test framework). Preferences require asking (desired coverage level, visual style, real-time vs batch).

Question Calibration

Multiple choice vs open-ended

• Multiple choice when there are 2-4 known options, the user may not know terminology, or speed matters. Always include a (Recommended) option with rationale.
• Open-ended when the answer space is unbounded or you need the user's mental model.

When a question is too broad

If the user would need more than 3 sentences to answer well, split it.

Rules

1. One decision per question. If your question contains "and," consider splitting.
2. No compound conditionals. Resolve X first, then ask the follow-up.
3. Ground in the codebase. "I see you use Express with middleware routing — should new auth endpoints follow the same pattern?"
4. Offer a recommendation when you can, tied to project context, not popularity.
5. Timebox complexity. If a question opens a 20-minute rabbit hole, flag it and offer to defer with a placeholder.

Extracting Implicit Requirements

Users say what they want; they rarely say what they need. Surface hidden requirements as follow-up questions — do not assume.

Extraction protocol

1. Acknowledge the stated requirement.
2. Surface the 2-3 most architecture-affecting hidden requirements as questions.
3. Do not dump all hidden requirements at once — prioritize, then circle back to polish.

Scaling Rules

Heuristic: count files touched, presence of external deps, scope definition, and whether data migration/backwards-compat is involved. When in doubt, ask one more question, not one fewer.

Anti-Patterns

1. Asking what the codebase can answer — search configs and deps first.
2. Batching unrelated questions — the user answers the easy one and skips the hard one. One at a time.
3. Implementation before purpose — resolve what and why before how. Transport choices without context are coin flips.
4. Accepting vague answers — "handle errors gracefully" means something different to everyone. Ask for a concrete example.
5. Skipping error/edge branches — edge cases are where bugs live. Ask "what happens at 0 items? 10,000? on failure?"
6. Leading questions — "we should use Redis here, right?" confirms your bias. Ask the open question.
7. Skipping the out-of-scope conversation — without explicit scoping, the feature grows silently.
8. Interviewing out of order — designing UI before the data model risks designing something the data can't support.

Migration Playbook

Migrations are the highest-risk work type Absolute Work handles: the code already runs in production, real users depend on it, and a botched migration breaks things that worked yesterday. This playbook makes migrations a first-class flow — safe, incremental, and reversible.

The core principle: never big-bang a migration you can do incrementally. Keep old and new coexisting behind a seam, move call sites in small verified batches, and keep a rollback at every step.

Migration Types

Identify the type during intake — it determines which sections below apply.

Phase A: Call-Site Inventory (before any code)

You cannot safely migrate what you have not counted. Build a complete inventory of everything that touches the thing being migrated.

Steps

1. Find the surface. Grep for the symbol, import, endpoint, or pattern being migrated. Capture every hit with file:line.
2. Classify each call site by shape — most migrations have 3-5 distinct usage patterns plus a long tail of one-offs.
3. Count and bucket. Record totals per pattern on the board. This sizes the migration and reveals whether a codemod is worth writing.
4. Find the blind spots. Dynamic usage (string-built imports, reflection, config-driven dispatch) won't show up in a grep. List where these could hide.
5. Map consumers. For API/contract/library migrations, identify external consumers (other services, published packages, clients) that a grep of this repo will miss.

Inventory table (write to the board)

## Migration Inventory
| Pattern | Example call site | Count | Codemod-able? | Notes |
|---------|-------------------|-------|---------------|-------|
| direct import | src/a.ts:12 | 47 | yes | mechanical rename |
| wrapped helper | src/lib/fmt.ts:8 | 1 | n/a | central shim point |
| dynamic dispatch | src/router.ts:30 | 3 | no | manual review |
Total call sites: 51 across 23 files

Phase B: Choose the Strategy

Default to incremental unless the surface is genuinely tiny. State the chosen strategy and its rationale on the board and in the spec.

Phase C: Establish the Coexistence Seam

For incremental migrations, old and new must run side by side. Create a seam so call sites can be moved one batch at a time without a flag day.

• Adapter/shim — a thin wrapper exposing the new implementation behind the old signature (or vice versa), so call sites switch without changing shape.
• Feature flag — gate new behavior so it can be toggled per environment or per user, and reverted instantly.
• Dual-write (data migrations) — write to both old and new stores during transition; read from old until new is verified, then flip reads, then stop writing old.
• Version negotiation (APIs) — serve both v-old and v-new; deprecate v-old only after consumers move.

The seam is itself a task on the board, and usually a blocker that must complete sequentially before any call-site batch runs.

Phase D: Incremental Rollout

Move the surface in small, independently verifiable batches — this is the onion-peel applied to migrations.

for each batch of call sites (grouped by module or pattern):
  1. migrate the batch (codemod for mechanical, manual for the tail)
  2. run tests for the affected modules → must stay green
  3. typecheck / build → must pass
  4. commit-worthy checkpoint (suggest commit; user commits)
  5. update the inventory: migrated N / total

Batch sizing: keep each batch small enough that if it breaks, the cause is obvious. Group by module boundary or by usage pattern. Migrate the central shim/helper first (one change unblocks many), then the mechanical bulk, then the manual tail last.

Codemod guidance

• Write the codemod against the patterns found in the inventory; dry-run it and diff before applying.
• Codemods handle the uniform majority; they will not handle dynamic dispatch, comments, or unusual formatting. Always hand-review the tail.
• Re-run the inventory grep after the codemod to confirm the count dropped to the expected remainder.

Phase E: Backwards Compatibility

Backwards-compat shims are temporary debt: add a task to the Deferred Work section to remove them once the migration completes and consumers have moved.

Phase F: Rollback Plan

Every migration records how to undo it, at every checkpoint — not just at the end.

1. Snapshot — the pre-migration commit hash on the board (## Rollback Point).
2. Per-batch reversibility — each batch is a clean checkpoint the user can revert to.
3. Flag kill-switch — if behind a feature flag, the rollback is flipping the flag, no redeploy.
4. Data rollback — for dual-write, document how to stop writing new and resume reading old; for destructive schema changes, ensure a backup exists before the change.
5. Cutover criteria — define what must be true before the old path is removed (all call sites moved, consumers migrated, monitoring clean for N days).

Never remove the old path in the same step that introduces the new one. Removal is its own task, gated on the cutover criteria being met.

Migration Anti-Patterns

Spec Writing

Reference for producing the design spec during Phase 2. Covers the document template, section scaling rules, writing style, the decision log, and the scored review protocol.

Spec Document Template

Write to docs/plans/YYYY-MM-DD-<topic>-design.md where <topic> is a short kebab-case slug (e.g. 2026-06-03-commenting-system-design.md).

# [Topic] Design Spec

## Summary
<!-- 2-3 sentences. What is being built and why. -->

## Context
<!-- What exists today. Why this change is needed. Link relevant code paths. -->

## Design

### Architecture
<!-- How the pieces fit together. ASCII diagram or description. -->

### Components
<!-- Each new/modified component with its responsibility and file path. -->

### Data Model
<!-- Schemas, tables, types. Code blocks for definitions. -->

### Interfaces / API Surface
<!-- Endpoints, function signatures, event contracts. Code blocks. -->

### Data Flow
<!-- Step-by-step for the key operations. -->

## Error Handling
<!-- Failure modes, retry strategy, user-facing error states. -->

## Testing Strategy
<!-- What to test, how, and at what level (unit/integration/e2e). -->

## Migration Path
<!-- Steps from current to new state. Remove if not applicable. -->

## Open Questions
<!-- Unresolved items. Remove if none remain. -->

## Decision Log
<!-- Key decisions from the interview. See format below. -->

Section Scaling Rules

Scale depth to complexity. Remove sections that would only say "N/A".

Simple (config change, utility, small fix) — ~1 page

Summary (2-3 sentences), Context (1-2 sentences), Components (bullets of what changes), Data Model / Interfaces only if changed, Testing Strategy (which tests). Skip Architecture, Data Flow, Migration Path, Open Questions, Decision Log.

Medium (new component, endpoint, moderate feature) — 2-3 pages

All core sections at moderate depth: Architecture (brief, no diagram needed), Components (table with name/responsibility/path), full Data Model in a code block, full Interfaces with request/response shapes, Data Flow (numbered steps), Error Handling (table), Testing Strategy (specific cases), Decision Log.

Complex (new system, migration, cross-cutting) — 4-6 pages

Every section at full depth: Architecture with a diagram and component relationships, Components table with dependencies, full schemas with relationships and indexes, all endpoints/functions with full types, primary + secondary data flows, comprehensive error handling with retry logic, test matrix by type, phased Migration Path with rollback, Open Questions with owners, full Decision Log.

Complexity heuristic

Writing Style

Be concrete, not abstract

Include file paths relative to repo root

The auth middleware at src/middleware/auth.ts validates the JWT before the request reaches src/api/comments/create.ts.

Use tables for comparisons and code blocks for interfaces/schemas

interface CreateCommentRequest {
  postId: string;
  body: string;
  parentId?: string; // for threaded replies
}

YAGNI

Remove anything not directly needed: don't spec future phases unless they constrain the current design, don't add "nice to have" sections, don't include sections that only say "N/A", fold one-sentence sections into a neighbor.

Decision Log Format

Record every decision where more than one reasonable option existed. The Rationale column is the most important — it prevents future re-litigation.

Include both decisions the user made explicitly and ones you recommended. Keep each cell to 1-2 sentences.

Scored Spec Review Protocol

After writing the spec, dispatch a separate reviewer subagent (generator-evaluator separation — the agent that wrote the spec does not review it).

Rubric

Thresholds

Reviewer prompt template

You are an independent spec reviewer. Grade this spec skeptically.
Do not give benefit of the doubt on vague sections.

Spec complexity tier: [SIMPLE | MEDIUM | COMPLEX]

--- BEGIN SPEC ---
{spec_content}
--- END SPEC ---

--- BEGIN INTERVIEW CONTEXT ---
{interview_summary}
--- END INTERVIEW CONTEXT ---

Score each criterion 1-5 using the rubric. Output (STRICT):

## Spec Review
- **Completeness**: {score}/5 - {justification}
- **Consistency**: {score}/5 - {justification}
- **Clarity**: {score}/5 - {justification}
- **Scope**: {score}/5 - {justification}
- **Testability**: {score}/5 - {justification}
- **Weighted Score**: {calculated}/5.0
- **Verdict**: Approved | Needs Work | Major Gaps

## Specific Issues (required if score < 4.0)
- [Section]: what is wrong and how to fix it

## What Was Done Well
- {1-2 strengths}

Reviewer approval is necessary but not sufficient — the user gate in Phase 2 is mandatory regardless of the reviewer's verdict.

Example Spec (abbreviated, medium tier)

# Commenting System Design Spec

## Summary
Add threaded comments (one level deep) to blog posts for logged-in users.

## Context
Blog at `src/app/blog/` uses Prisma + PostgreSQL. No commenting today.

## Design
### Architecture
New API routes at `/api/posts/:postId/comments`, new `comments` table,
React components in `src/components/comments/`.

### Components
| Component | Responsibility | File Path |
|---|---|---|
| CommentThread | Renders comments + replies | `src/components/comments/CommentThread.tsx` |
| CommentForm | Input form | `src/components/comments/CommentForm.tsx` |
| comments API | CRUD endpoints | `src/app/api/posts/[postId]/comments/route.ts` |

### Data Model
Comment: id, body, postId, authorId, parentId (nullable), createdAt, updatedAt.
Indexes on [postId, createdAt] and [parentId].

## Testing Strategy
11 tests: 8 integration (CRUD + auth + pagination + nesting), 2 unit, 1 e2e.

## Decision Log
| Decision | Chosen | Rationale |
|---|---|---|
| Nesting depth | 2-level | Avoids recursive queries, covers 90% of cases |
| Pagination | Cursor-based | Reliable with concurrent inserts |

Verification Framework

Every task proves it works before closing. Verification runs in two layers — signals (objective, binary) and evaluator (subjective, scored) — with generator-evaluator separation throughout. This reference also defines the three mandatory tail tasks that close every board.

TDD Workflow Per Task

Red → Green → Refactor

RED:      write tests describing the desired behavior → tests FAIL
GREEN:    write the minimum code to pass → tests PASS
REFACTOR: clean up while keeping tests green → tests PASS

Steps

1. Read the acceptance criteria from the task's plan.
2. Write test file(s) encoding each criterion as a test case.
3. Run tests — confirm they FAIL (red proves the tests are meaningful).
4. Implement to make each test pass, one at a time.
5. Run tests — confirm they PASS (green).
6. Refactor — rename, extract, simplify — keeping tests green.
7. Final run — all tests pass, lint clean, types check.

Test categories per task

Follow the project's existing test-naming convention; if none, use describe("Thing", () => it("should X when Y")).

Layer 1: Verification Signals (Binary Gate)

Run via the project's own scripts — never raw tools.

Detect available commands from package.json scripts, Makefile, pyproject.toml, and CI config. If ANY signal fails, the task goes straight back to the generator to fix (up to 2 signal retries). Signal failures are unambiguous — no evaluator needed to diagnose a failing test or broken build.

If time-constrained, verify in priority order: Tests → Build → Type Check → Lint → Format.

Layer 2: The Evaluator (Scored Gate)

If all signals pass, dispatch a separate evaluator subagent. Self-evaluation has systematic bias — generators over-praise their own work and talk themselves out of legitimate issues. A fresh, skeptical context sees the work as a reviewer would.

Complexity gating

Scored rubric (code tasks)

Rubric adaptations: test tasks → swap Code Quality for Assertion Quality, raise Test Coverage to 25%. docs tasks → Clarity/Accuracy replaces Code Quality; Coverage/Completeness replaces Test Coverage. config/infra → Integration Safety to 25%, add an Idempotency check.

Thresholds

Evaluator prompt template

## Evaluator Task: {AW-XXX} - {Title}

You are an independent evaluator. Grade this work skeptically and honestly.
Do not assume good intent. Look for gaps, shortcuts, incomplete work, hidden bugs.

### Acceptance Criteria
{criteria — what "done" means}

### Files Modified / Git Diff
{the actual diff of all changes}

### Test Output / Lint / Type / Build Output
{verification signal results}

### Project Conventions
{detected conventions}

Score each dimension 1-5 using the rubric. Output (STRICT):

#### Evaluation: AW-{XXX}
- **Correctness**: {score}/5 - {justification}
- **Code Quality**: {score}/5 - {justification}
- **Completeness**: {score}/5 - {justification}
- **Test Coverage**: {score}/5 - {justification}
- **Integration Safety**: {score}/5 - {justification}
- **Weighted Score**: {calculated}/5.0
- **Verdict**: PASS | NEEDS WORK | FAIL

#### Specific Feedback (required if score < 4.0)
- What is wrong, what the fix looks like, which files need changes.

#### Bugs Found
- {file:line references}

#### What Was Done Well
- {1-2 strengths}

The evaluator receives only outputs and criteria — never the generator's reasoning. This prevents it from rationalizing decisions it should be questioning.

Iterative refinement loop

for iteration in 1..5:
  evaluator grades the work
  if weighted score >= 4.0: PASS, exit
  if iteration >= 3 AND score stagnant/declining: FAIL, escalate with full history
  if score < 3.0 on any iteration: FAIL immediately, escalate
  else: generator makes TARGETED fixes from the feedback (not a rewrite); loop

Track scores per iteration on the board. A dropping score means the generator is thrashing — stop and escalate. On retry the generator receives: per-dimension scores, the specific-feedback section, the bugs list, and the instruction "Fix ONLY what the evaluator flagged."

Platform fallback

Without subagent support, switch context explicitly: "— EVALUATOR MODE — I evaluate the work I just completed as a different, skeptical reviewer. I do not reference my implementation intent; I judge only what is visible in the code and test output." Weaker than true separation, but strictly better than no gate.

Integration Verification (post-wave)

After a wave, if its tasks share dependencies or feed the next wave: verify import resolution, run the combined test suite (or tests for all files modified in the wave), run the build (watch for circular-dependency warnings), and smoke-test at runtime if applicable. After the final wave, run the FULL suite and build to catch regressions before CONVERGE.

What NOT to Do on Failure

• Do NOT suppress or skip failing tests.
• Do NOT add @ts-ignore, // eslint-disable, or # type: ignore to pass checks.
• Do NOT reduce coverage or modify existing passing tests to accommodate a bug.
• Do NOT mark a task done while any signal fails.

Mandatory Tail Tasks

Every task graph ends with these three, in order. They are real tasks on the board with acceptance criteria — not afterthoughts.

Third-to-last — Self Code Review (review)

Review all changes since the rollback point. Work the review pyramid bottom-up: Security → Correctness → Performance → Design → Readability → Convention → Testing. Classify findings [MAJOR] / [MINOR]. Fix all [MAJOR] immediately and reasonable [MINOR]. Re-run after fixes. Acceptance: zero [MAJOR] remaining; all [MINOR] documented (fixed or explicitly deferred). Depends on all implementation/test/docs tasks. If absolute-simplify is installed, run it on the working changes here.

Second-to-last — Requirements Validation (verify)

Compare all changes against the original prompt, intake summary, and spec. Verify every success criterion and constraint is satisfied. Acceptance: every success criterion demonstrably met; gaps loop back to EXECUTE until resolved. Depends on the self code review.

Last — Full Project Verification (verify)

Run all available checks via the project's package-manager scripts, skipping any not configured: Tests → Lint → Typecheck → Build. Acceptance: all available checks pass; failures are fixed and re-run until green. Do not mark the board completed until every available check passes and its output is recorded on the board. Depends on requirements validation.