writing-plans

<EXPLICIT-MODE-GATE>
If activation mode is explicit (`~/.config/aegis/config.toml` has
`activation_mode = "explicit"`, or `AEGIS_ACTIVATION_MODE=explicit` is visible
in the environment) and the current user request did not explicitly invoke
Aegis or this skill by name, exit back to the fast path: answer concisely
without this workflow's checklist, ceremony, or document requirements. If the
user explicitly named Aegis or this skill, proceed normally.
</EXPLICIT-MODE-GATE>

# 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
→ Mechanical or bounded change with no durable boundary (no new owner,
  contract, schema, public API, migration, or compat surface)? → **Use
  Planless Slice Lane without a parent document.** Emit the compact Slice Card,
  skip the plan file, and record the change in the commit message.
→ 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 → select and announce the execution route; proceed unless a real authorization or safety boundary requires the user
→ 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. Chosen TDD route. One verified commit per coherent Task or slice.

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.

Strict RED / GREEN steps belong only to an explicit user/project TDD request or
`TDD Route: strict`. With TDD mode `off` and no strict route, plan the minimum
implementation and proportional regression/verification steps; do not prescribe
a TDD cycle from risk alone.

### TDD Route Guard

Before task decomposition, every plan that includes implementation work must
record:

```text
TDD Route:
- Mode: off | auto
- Decision: strict | light | skipped
- Strict authority: explicit user/project request | recorded auto decision | not applicable
- Strict signals:
- Light eligibility:
- TDD-fit exception:
- Test posture: diagnostic reproduction | post-change regression | strict RED test
- Reason:
- Verification:
```

In `off`, record `Decision: skipped` unless an explicit user/project strict
request overrides it. The record makes the boundary reviewable; it does not
load `test-driven-development`. An approved plan or a risk label alone is not
strict authority; matching risk is a signal that requires this owner to record
`recorded auto decision` as the authority.

In `auto`, select `strict` when any behavior, bugfix, shared/core, contract,
persistence, permission, migration, producer/consumer, or meaningful
regression signal applies. Select `light` only when tiny, low-risk,
single-owner, no behavior change or strict signal, and an obvious focused check
all apply. Absence of an explicit user TDD request is never evidence for
`light`. Unknown risk returns to requirement, debugging, or plan review.

Only `Decision: strict` with stated strict authority may prescribe `Write
failing test`, `Verify RED`, `GREEN`, or `REFACTOR` as task steps. Otherwise,
write the minimum change plus diagnostic reproduction or post-change regression
as appropriate. In `auto`, if the plan lacks a recorded decision, return to
route selection before writing implementation tasks; never infer `strict`
during decomposition.

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

**Execution context:** Reuse the current branch/workspace by default. A branch
needs independent history; a worktree needs concurrent checkout, blocking
unrelated dirty state, or explicit user/repository authority.

**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>
```

Project authority overrides work