design

name	design
description	When the user is defining the technical solution after discovery — contracts, task split, risk register, sequencing. Owns scripts — validate_plan. Do NOT use for problem investigation (see specify), implementation (see execution), or PR review (see review).
metadata	{"type":"workflow"}

Design Workflow

CANARY: design-loaded-2026-05-19-e08675ccb0a5c932

Owns sections 5–6 of status/specification.md (contracts, risks) and creates status/plan.md (task split). Reads sections 1–4 of status/specification.md to understand what the spec already covers.

Steps

Step 1: Define the technical solution

Translate the chosen option into a concrete technical design.

• Architecture overview: how the change fits into the existing system
• Data flow: how data moves through affected services (request/response, events, jobs)
• State changes: what data is created, updated, or deleted and where
• Technology choices: any new libraries, tools, or patterns (justify each)
• What is NOT changing: explicit boundaries to prevent scope creep

Step 2: Define contracts

For every interaction between components:

• API contracts: request/response schemas, status codes, error formats
• Event contracts: message schemas, routing keys, retry policies
• Database changes: schema modifications, migration approach (always forward-compatible)
• Configuration: new env vars, feature flags, deployment parameters

Use concrete examples (JSON payloads, SQL migrations, config snippets).

Step 3: Split into tasks

Break the implementation into ordered, independently testable tasks.

For each task:

• What: specific deliverable
• Where: which files/services
• Dependencies: what must be done first
• Gate (measurable acceptance condition): the objective metric and threshold that proves this task is done — written <metric> <op> <threshold> (e.g. p95_latency_ms <= 200, line_coverage >= 0.90), not just "tests pass." Derive it from the spec's success criteria. The gate-check skill defines the grammar the gate must follow so it can be checked mechanically; reserve a non-numeric gate for a condition that genuinely cannot be reduced to a number.
• Tests: test file path(s) and one or more test function names using test_<what>_<condition>_<expected_result> naming, each with a one-sentence assertion that can be written as a failing test before any production code is touched. These are copied verbatim into the task payload so the worker writes them RED first.
• Estimated effort: Small (< 1h) / Medium (1-4h) / Large (4h+)

Recommended: tasks should be small enough to be a single commit.

Every task carries a Gate. As execution finishes a task it records the gate's evidence — measured value, command run, commit SHA, environment provenance — in the plan's Evidence log; that record is what review and ship audit. The Gate column is required for new plans; plans predating this convention are tolerated (the gate-check engine and review / ship degrade gracefully when a plan has no Gate column).

Step 4: Anticipate risks

For each risk:

• What could go wrong: specific failure scenario
• Likelihood: Low / Medium / High
• Impact: Low / Medium / High
• Mitigation: what to do to prevent or handle it
• Rollback plan: how to undo if it goes wrong

Pay special attention to:

• Backwards compatibility (API consumers, data formats)
• Data integrity during migration
• Performance under production load
• Deployment ordering (if multi-service)

Step 5: Produce design output

Load references/template-specification-tail.md when appending contracts and risks (sections 5–6) to status/specification.md. Load references/template-plan.md when creating status/plan.md.

After writing the files, confirm the plan's structure:

python3 "${CLAUDE_SKILL_DIR}/scripts/validate_plan.py" --input status/plan.md

It checks the plan has the required sections (Technical solution, Implementation tasks, Evidence log, Sign-off) and that the task table carries the required columns including the measurable Gate — shape only. The gate-check skill's run_gate.py then audits the gate values and evidence themselves (add --strict there to require a gate on every task).

Step 6: Publish the annotatable plan

Generate the reader once the validator passes, and hand both files to the user in the same reply. The plan is what the user signs off on, so it goes back in a form they can mark up section by section rather than as a path to open themselves:

Run create_reader.py (in claude-arsenal/scripts/; it imports markdown, which uv run --with markdown python3 supplies):

create_reader.py --input status/plan.md --output-dir status

Auto-discovery only looks for spec files, so the plan is named explicitly — which means --output-dir has to travel with it. Point both flags at arsenal/project/<WORKSPACE>/ when a workspace plan exists, or the reader lands back in status/ beside a plan it does not render. Writes plan-reader.html and plan-annotated.md there and prints both paths; the step is done when those two paths exist and the user has been given the HTML. The reader keeps its notes under a namespace of its own, so plan annotations never overwrite the spec's, and its export is named <project>-plan-notes-<date>.md.

When a returned export arrives — a path in ~/Downloads, an upload, a paste — move it into the plan's directory beside the reader and commit it. The annotations are the sign-off record for this plan; left in Downloads they are gone by the next session.

---

Abbreviation

Abbreviated design = Step 1 (solution overview, 1 paragraph) + Step 3 (task list only). Whether abbreviation is allowed depends on project conventions documented in the host repo's CLAUDE.md.

Workspace-aware paths

When arsenal/project/<WORKSPACE>/ exists, write the plan to arsenal/project/<WORKSPACE>/plan.md (and the contracts/risks tail to the workspace's spec.md) instead of status/plan.md. Otherwise use status/ as above. The validator takes the path via --input; point it at whichever file was written.