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, Requirement Ready Check, 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`, `Requirement Ready Check`, `Files`, `Compatibility`,
`Existence Check`, `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 a compact `Requirement Ready Check` before task decomposition unless the
input is already an approved plan/spec whose acceptance boundary is explicit:

```text
Requirement Ready Check:
- Requirement source refs:
- Goals and scope refs:
- User / scenario refs:
- Requirement item refs:
- Acceptance / verification criteria refs:
- Open blocker questions:
- Decision: ready | needs-source | needs-goal-alignment | needs-scenario | needs-acceptance-criteria | needs-clarification | needs-user-decision | blocked
```

If the decision is not `ready`, do not create implementation tasks. Return to
the requirement/spec owner with the smallest missing evidence or decision. A
task intent, conversation, or agent inference can be cited as a candidate
source, but it is not durable requirement authority by itself.

Use a compact `Existence Check` before task decomposition when a plan would add
a new owner, skill, artifact, host adapter, fallback, compatibility path,
workflow step, or benchmark metric. Use
`docs/current/AEGIS_MINIMALITY_REFERENCE.md` as the reference and keep the check
advisory. Do not force it onto plans that only reuse