/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

→ Existing parent plan/spec and a tiny execution slice? → **Use Planless Slice Lane.** → 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.** → Approved spec/requirements for a new workstream or an escalation trigger? → **Write an implementation plan for an engineer with no prior task context.**

For a durable plan: confirm scope and acceptance, map current owners/files, record the TDD route, decompose into executable tasks, define verification and retirement, self-review, save, then select the execution route. Proceed unless a real authorization or safety boundary requires the user.

Bind tasks to the requested user outcomes: object, actions, conditions, and deliverables. Include the final delivery step and evidence at the user-visible seam, not only implementation/tests. Keep unmet needs and dependencies explicit; project-wide goals do not authorize work outside this request. Reuse the existing scope/acceptance slots; no extra goal artifact is required.

This plan is method-pack guidance, not authoritative completion.

TDD Route Guard

Before task decomposition, record `TDD Route` with mode (`off | auto`), decision (`strict | light | skipped`), authority, test posture, reason, and verification.

Strict RED / GREEN steps belong only to an explicit user/project TDD request or `TDD Route: strict`. In `off`, use `skipped` unless explicit strict authority overrides it. An approved plan or a risk label alone is not strict authority.

In `auto`, select `strict` for behavior, bugfix, shared/core, contract, persistence, permission, migration, producer/consumer, or meaningful regression signals. Select `light` only when the work is tiny, low-risk, single-owner, has no behavior change or strict signal, and has an obvious focused check. Absence of an explicit user TDD request is never evidence for `light`; the auto decision itself must be recorded.

If risk remains unknown, return to requirements, debugging, or plan review before task decomposition; do not infer a TDD route from uncertainty.

Only a `strict` decision with stated authority may prescribe failing-test, RED, GREEN, and REFACTOR steps. Otherwise plan the minimum change plus diagnostic reproduction or post-change regression. A missing auto decision returns to route selection before implementation tasks.

Entry And Artifact Choice

**Announce at start:** on the plan-writing route, say that this skill is creating the implementation plan. On `Planless Slice Lane`, announce the lane instead and do not claim a plan is being created.

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

**Default plan path:** `docs/aegis/plans/YYYY-MM-DD-<feature-name>.md`. Plans do not go in `work/`; user and repository authority override the default.

Planless Slice Lane

Use `Planless Slice Lane` before writing or saving a plan when one of these entry conditions holds:

• a parent spec or parent plan already defines the workstream, and the current

request is executing or refining one bounded task from that parent

• the change is mechanical or bounded and needs no parent document (the

no-parent branch under `# Execute`)

and both of these are true:

• no new owner, contract, schema, public API, architecture boundary, migration,

persistence, security/permission, distribution/release surface, or unclear verification boundary appears

• the slice can be described by a `Slice Card`

The lane preserves long-task continuity without turning execution bookkeeping into durable planning artifacts. A parent scope or acceptance mismatch returns to the parent plan/spec instead of spawning a micro-plan.

Do not save a new plan. Emit a compact `Slice Card`:

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

On the no-parent branch, `Parent plan/spec:` is `none — direct bounded request`.

Aegis Project Workspace

Workspace creation is lazy and follows project authority. The Aegis Method Pack repository must not create or ship a live `docs/aegis/` workspace. When a durable plan must initialize or update another project's workspace, read the `## Workspace Save Detail` section of `expanded-planning-guidance.md`. It owns the `<aegis-workspace-helper>` and `INDEX.md` command detail, not the decision to create a plan.

Default Plan Surface

Compact output contract: express these as natural plan content, not a stack of cards: `Aegis Visibility`, approved scope and plan basis, required baseline refs, files/owners, compatibility boundary, `Change Necessity`, TDD route, tasks, verification, risks, and retirement. Keep conditional structures silent unless their trigger below fires.

`Aegis Visibility` is normally one sentence explaining which owner, contract, retirement, compatibility, or verification pressure makes a durable plan useful. Structured trace belongs only to audit, debug, release, long-task review, or explicit request.