persist-plan

Persist Plan Skill

Capture a plan or architectural decision as a discoverable, structured file so that any agent or team member can find it later without re-deriving the context.

When planning directly against a GitHub issue, use github-issue-planning for issue-backed plan persistence on GitHub (prefer MCP, fallback to gh CLI). Use this skill for local .agentic/plans/ persistence.

Step 1 — Gather Plan Metadata

Collect (or confirm) the following before writing:

1. Title — a short, descriptive phrase (e.g., "Introduce CQRS in order service", "Migrate auth to hexagonal ports"). Used for the filename and H1 heading.
2. Type — one of: feature, refactor, architecture, investigation, decision.
3. Status — one of: draft, in-progress, completed, superseded.
4. Affected areas — which modules, bounded contexts, or services does this plan touch?
5. Author — the agent name or human handle that produced the plan.

Step 2 — Derive the Filename

Build the filename as:

YYYY-MM-DD-{kebab-case-title}.md

Examples:

2026-03-06-introduce-cqrs-in-order-service.md
2026-03-06-migrate-auth-to-hexagonal-ports.md

• Use today's date in YYYY-MM-DD format.
• Slugify the title: lowercase, replace spaces and special characters with hyphens, strip leading/trailing hyphens.
• If a file with the same slug already exists for today, append -2, -3, etc.

Step 3 — Write the Plan File

Save to .agentic/plans/{filename} using the template from plan-template.md.

Mandatory sections:

# {Title}

**Date**: YYYY-MM-DD
**Type**: feature | refactor | architecture | investigation | decision
**Status**: draft | in-progress | completed | superseded
**Affected**: [list of modules / bounded contexts / services]
**Author**: {agent-name or handle}

## Context

What situation, problem, or question prompted this plan?
Be specific — a reader unfamiliar with the moment must understand the trigger.

## Goals

What does this plan aim to achieve?
Use bullet points. Each goal must be verifiable (done / not done).

## Approach

How will the goals be achieved?
Include the key decisions made, alternatives considered, and the rationale for
the chosen direction. Reference relevant fragments, ADRs, or tickets where applicable.

## Steps

Ordered list of concrete tasks derived from this plan.

1. ...
2. ...

## Risks & Open Questions

- Any unknowns, blockers, or decisions that still need to be made.

## Outcome

(Fill in when status moves to `completed` or `superseded`.)
What was the actual result? Did the plan change during execution? Why?