/writing-plans

name: writing-plans
description: "Use when you have an approved spec or written requirements for a multi-step task that needs a durable plan document before touching code. Small, single-owner, or fast-path tasks do not need this skill."

<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:

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:

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