writing-plans

# Execute

→ Have an existing parent plan/spec and a tiny execution slice? → **Use Planless Slice Lane.**
  1. Emit a compact Slice Card: goal, parent plan/spec, files, boundary, verification, stop
  2. Update the parent workstream checkpoint/evidence/drift state if persistent state is needed
  3. Do not save a new plan for the micro-slice
→ Have approved spec/requirements for a new workstream or an escalation trigger? → **Write implementation plan. Assume engineer has zero context.**
  1. Scope check: fact/assumption/unknown, baseline, Ripple Signal Triage, compatibility boundary, dual-track needs
  2. File map: what files created/modified, clear boundaries, follow existing patterns
  3. Bite-sized tasks (2-5 min each): exact file paths, complete code, exact commands, expected output
  4. Self-review: spec coverage, placeholders, type consistency, compatibility, verification, dual-track
  5. Save → offer execution choice (subagent-driven or inline)
→ Plan must answer: problem, baseline, files, compat, verification, risks, retirement.
→ Escalate from Planless Slice Lane to a durable plan when the slice adds a new owner, contract, schema, public API, architecture boundary, migration, persistence, security/permission, distribution/release surface, or unclear verification boundary.

# Writing Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

This skill is the canonical planning workflow for multi-step implementation work. Use it to convert approved specs or requirements into plans that are executable, testable, impact-aware, and bounded by compatibility and authority constraints.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Context:** This should be run in a dedicated worktree (created by brainstorming skill).

**Input:** approved requirements, a Spec Brief, or a Design Spec.

**Save plans to:** `docs/aegis/plans/YYYY-MM-DD-<feature-name>.md`
Plan always goes to `plans/` — never to `work/`.
(User preferences for plan location override this default.)

Exception: if an existing parent plan/spec already owns the current tiny
execution slice, use `Planless Slice Lane`. Do not save a new plan. Emit a
compact `Slice Card` in the conversation or the active long-task checkpoint
instead:

```text
Slice Card:
- Goal:
- Parent plan/spec:
- Files:
- Boundary:
- Verification:
- Stop:
```

If `docs/aegis/` does not exist and configured Aegis workspace support is
available, initialize the target project first:

```bash
python <aegis-workspace-helper> init --root <target-project-root>
```

If installed Aegis workspace support is unavailable, initialize the workspace manually:
  1. Create `docs/aegis/README.md` and `docs/aegis/INDEX.md`
  2. Create `docs/aegis/BASELINE-GOVERNANCE.md` from template
  3. If the project has code, create `docs/aegis/baseline/YYYY-MM-DD-initial-baseline.md`
Then save the plan and append to `docs/aegis/INDEX.md`. Prefer:

```bash
python <aegis-workspace-helper> append-index --root <target-project-root> --path docs/aegis/plans/<filename>.md --kind plan --title "<title>"
python <aegis-workspace-helper> check --root <target-project-root>
```

## Scope Check

If the input is a Spec Brief, keep the plan scoped to the pinned
what/why/acceptance and do not expand into a formal design unless new
architecture, contract, migration, or cross-module uncertainty appears.

Compact output contract before writing the plan: `Plan Basis`,
`BaselineUsageDraft`, `Files`, `Compatibility`, `Architecture Integrity Lens`,
`Plan Pressure Test`, `Plan-Time Complexity Check`, `Tasks`, `Risks`, and
`Retirement`. Expand only where the approved scope, risk, or verification
surface requires it.

Use a compact `BaselineUsageDraft` whenever the plan depends on specific
baseline docs or current-authority refs:

```text
BaselineUsageDraft:
- Required baseline refs:
- Delivered context refs:
- Acknowledged before plan refs:
- Cited in plan refs:
- Missing refs:
- Decision: continue | needs-baseline-readback | needs-verification | pause-for-user | blocked
```

`Delivered context refs` is optional host-projected bookkeeping only. It is not
authoritative proof that a host injected or the model internally consumed a
context payload. The artifact exists to make baseline/context attention drift
visible before and during planning.

Use the `Architecture Integrity Lens` before task decomposition when an
executable plan may still encode responsibility overlap, a wrong canonical
owner, a caller-side fallback, a stale path carrying real logic, or a missed
higher-level owner / contract / source-of-truth simplification. Keep it compact:
invariant, canonical owner / contract, responsibility overlap, higher-level
simplification, retirement / falsifier, and verdict.

Use a compact `Plan Pressure Test` before task decomposition:

```text
Plan Pressure Test:
- Owner / contract / retirement:
- Architecture integrity / higher-level path:
- Verification scope:
- Task executability:
- Pressure result: proceed | revise plan | return to design
```

The pressure test is not an approval gate and should not redesign an approved
spec without cause. It exists to catch owner / contract / retirement risk,
missing verification, and tasks that are too vague to execute safely.

Use a compact `Plan-Time Complexity Check` before writing task steps when the
plan changes maintained source files, core owners, handlers, routers, managers,
shared utilities, adapters, or fallback paths:

Use `using-aegis/references/complexity-governance.md` for the sha