Use when the user asks for a software engineering plan, implementation plan, refactor plan, migration plan, rollout plan, bug-fix plan, performance optimization plan, security change plan, DevOps / CI/CD plan, technical execution plan, or review of an existing engineering plan. Produces phased, executable, independently verifiable, reviewable, rollback-aware plans with strict phase gates, plan-to-code completeness, benefit validation, and chain-state logging evidence for software engineering work.
SE Good Plan
Purpose
Use this skill to write or review software engineering plans that are practical
for engineers, reviewable by technical leads, and understandable to
stakeholders.
Plans must remain phased, executable, verifiable, reviewable, rollback-aware,
and now independently verifiable at every phase gate.
A good plan is not a generic TODO list or a high-level roadmap. It must explain
what to do, why it should be done that way, how to prove it worked, what can go
wrong, and how to recover.
Use This Skill When
The user asks for an engineering plan, implementation plan, rollout plan,
migration plan, refactor plan, bug-fix plan, or technical execution plan.
The user asks for a performance optimization, security change, DevOps, CI/CD,
data migration, architecture migration, or release plan.
The user asks to split software work into phases.
The user asks to make a plan more executable, reviewable, or engineering-grade.
The user asks whether an existing software engineering plan is complete,
risky, or ready for review.
Do not use this skill for pure product requirement clarification unless the
request is to convert requirements into engineering execution. Do not over-plan
tiny, low-risk edits.
Core Rules
Start from the problem definition, not from implementation steps.
Separate facts, assumptions, constraints, risks, and open questions.
Do not invent project-specific facts such as architecture, databases,
services, traffic, deployment model, or business rules.
Do not invent schedules, staffing, resource commitments, deadlines, launch
dates, or maintenance windows. If they are not provided, keep them unknown or
list them as assumptions to confirm.
If context is missing, keep moving by adding a Discovery phase, assumptions,
and Open Questions instead of pretending certainty.
Choose plan depth from task complexity and risk.
Break medium and high-risk work into progressive phases.
Each phase must include entry criteria, checks, tasks, deliverables,
validation, exit criteria, review plan, risks, fallback, and next-phase gate.
Each phase must be independently verifiable. A phase cannot require a later
phase to prove its own exit criteria, and a later phase cannot retroactively
close an earlier phase.
Do not proceed to the next phase unless the current phase is 100% complete or
the user explicitly approves proceeding with recorded residual risk. If a
phase is incomplete, ambiguous, or depends on future evidence, pause instead
of continuing.
Move high-risk and high-uncertainty validation earlier.
Production-impacting work must include release, rollback, fallback or
degradation, observability, and post-release validation.
Data changes must include migration, idempotency, retry or resume behavior,
validation, and rollback or compensation.
Security-sensitive work must include permission boundaries, sensitive-data
handling, abuse cases, audit logging, and security review.
Implementation plans must include plan-to-code completeness evidence. Do not
count protocols, interfaces, schemas, entry points, scaffolding, mock or fake
data, demo scripts, and test-only wiring as completed implementation unless the
production path is wired, exercised, and evidenced.
Plans must state expected benefits, not only planned work. Acceptance must
include correctness validation and benefit validation, such as speed,
accuracy, reliability, cost, conversion, or operational-toil improvements.
Plans must include logging design for the affected change chain. Logs must
capture key states, success signals, failure signals, and failure reasons so
operators can tell where the change succeeded, failed, or became ambiguous.
Use measurable acceptance criteria. Avoid vague promises like "optimize",
"improve", "support", "handle", or "complete" unless they are made specific.
Generation Workflow
1. Classify The Task
Classify the request before writing the plan:
feature development
bug fix
refactor
migration
data migration
architecture change
performance optimization
security change
DevOps / CI/CD
release / rollout
other software engineering work
For task-specific requirements and phase patterns, read
references/plan-patterns.md when the task maps to one of those types.
2. Assess Complexity And Risk
Use this scale:
Level
Typical signals
Low
single module, no production data, easy rollback, limited user impact
Medium
multiple modules, API/config/deployment changes, controlled production risk
High
multiple services, data migration, core workflows, difficult rollback
Critical
core business path, irreversible data, security/auth/payment/finance, many teams
Use this proportionality guide unless the request provides stronger constraints:
Complexity
Plan depth
Typical phase count
Low
Lightweight
2-3
Medium
Standard
4-5
High
Full
6-8
Critical
Full with stronger review gates
7-10
Force a Full Plan when any of these are true:
production data migration
authentication, authorization, permission, or sensitive-data boundary change
payment, billing, accounting, order, asset, or core business workflow change
core API compatibility risk
large user-visible rollout
irreversible or hard-to-rollback change
cross-system architecture migration
high availability, disaster recovery, or high-concurrency requirement
external dependency replacement
3. Choose Output Depth
Use Lightweight Plan for low-risk, narrow work. Include:
Background
Goals
Non-goals
Implementation steps
Acceptance criteria
Test plan
Risks and rollback
Use Standard Plan for ordinary engineering work with multiple moving parts.
Include:
Metadata
Background
Problem Definition
Goals
Non-goals
Constraints And Assumptions
Current State
Plan Summary
Overall Technical Design
Phased Execution Plan
Implementation Completeness Matrix
Risks, Dependencies, And Mitigations
Testing And Validation Strategy
Release, Rollback, And Fallback Strategy
Observability And Success Metrics
Open Questions
Change Log
Plan Quality Checklist
Use Full Plan for high-risk, production-impacting, data-impacting,
security-impacting, or architecture-impacting work. Add:
Complexity And Risk Assessment
Alternatives And Tradeoffs
Phase Gate Overview
Data Migration Strategy
API / Compatibility Strategy
Security And Permission Review
Post-release Verification And Cleanup
Decision Log
All Standard and Full plans must include this metadata contract unless the user
requests a shorter inline answer:
- Created:
- Updated:
- Version:
- Status: Draft | Reviewing | Approved | In Progress | Blocked | Completed | Deprecated
- Owner / Responsible:
- Related Systems:
- Related Links:
- Risk Level:
- Plan Type: Lightweight | Standard | Full
Use this dependency table in Standard and Full plans when any dependency exists
or must be discovered:
| Dependency | Type | Current Status | Blocking Risk | Handling Plan |
|---|---|---|---|---|
| ... | system / person / data / environment / third-party | Ready / Pending / Unknown | ... | ... |
If the dependency state is unknown, do not omit it. Mark it Unknown and tie it
to a phase gate or open question.
Use this implementation completeness matrix in every implementation, refactor,
migration, bug-fix, DevOps, or release plan that expects code changes:
| Plan Item | Expected Behavior | Production Code Path | Integration Entry | Test Evidence | Runtime / Log Evidence | Mock / Stub Exposure | Status |
|---|---|---|---|---|---|---|---|
| ... | ... | file, function, module, or command | UI, API, job, CLI, pipeline, or service path | test path and assertion | command, log, trace, or artifact | none / test-only / blocks completion | planned / landed / partial / stub-only / mock-only / deferred |
Only landed means complete. stub-only, mock-only, partial, and
planned cannot satisfy an exit gate unless the user explicitly accepts the
remaining risk and the follow-up location is recorded.
Use this change-chain logging matrix in every plan that changes runtime
behavior, release flow, data movement, jobs, APIs, user workflows, or operator
procedures:
| Change Link | Key State | Success Signal | Failure Signal | Failure Reason Field | Correlation / Trace Field | Log Level | Consumer |
|---|---|---|---|---|---|---|---|
| ... | queued / started / validated / committed / published / rolled back | ... | ... | error_code / reason / exception / validation_error | request_id / job_id / trace_id / entity_id | info / warn / error | on-call / owner / dashboard / audit |
The logging design must cover the chain from trigger to side effect, not only
the final result. If a state cannot be logged safely, explain the privacy,
security, or cost reason and define an alternate metric, trace, or audit event.
Use this phase dependency and gate matrix in every Standard or Full plan:
| Phase | Independent Verification | Forbidden Future Dependency | Exit Evidence | Completion Required Before Next Phase | Proceed Decision |
|---|---|---|---|---|---|
| Phase N | test, log, review, artifact, or measurement available inside this phase | no Phase N+1 artifact needed to close Phase N | ... | 100% complete or explicit user approval with recorded residual risk | proceed / pause |
If a phase needs evidence from a later phase before it can close, the phase
boundary is wrong. Move that validation earlier, split the phase, or mark the
plan blocked until the dependency is resolved.
4. Extract Context Honestly
Before writing the plan, identify what the user already provided:
project or system
current problem
target outcome
non-goals or constraints
current system state
affected modules, APIs, data, dependencies, environments, or users
production impact
deadline, rollout, compliance, or review requirements
If important information is missing, list it under Open Questions. If a
temporary assumption helps planning, put it in an assumptions table:
If missing context blocks detailed planning, make Phase 0: Discovery the
first phase and define exactly what evidence must be collected.
5. Define The Problem And Goals
The problem definition must distinguish:
current behavior
expected behavior
gap
affected users, modules, data, APIs, and deployment surfaces
Goals must be testable. Non-goals must control scope. If a phrase is vague,
rewrite it with a metric, scenario, artifact, or acceptance criterion.
Each material goal must include the expected benefit and how it will be tested.
If the benefit baseline or target is unknown, mark it Unknown and make
baseline discovery part of Phase 0 or an early validation gate.
6. Build The Phased Plan
Phase boundaries must be strict. Each phase must produce evidence that can be
checked before the next phase starts. Do not create a plan where Phase 2 can
only be validated after Phase 3 or where downstream rollout evidence is needed
to claim an earlier build, migration, or validation phase is complete.
For every Standard or Full Plan, each phase must use this schema:
### Phase <N>: <Name>#### Objective#### Entry Criteria#### Entry Criteria Checks
| Entry Criterion | Check Method | Evidence / Output | Owner |
|---|---|---|---|
#### Design Approach#### Implementation Tasks#### Deliverables#### Implementation Completeness Evidence
| Plan Item | Production Code Path | Integration Entry | Test Evidence | Runtime / Log Evidence | Mock / Stub Exposure | Status |
|---|---|---|---|---|---|---|
#### Logging And Observability Design
| Change Link | Key State | Success Signal | Failure Signal | Failure Reason Field | Correlation / Trace Field | Log Level | Consumer |
|---|---|---|---|---|---|---|---|
#### Testing And Validation
| Validation Type | Validation Item | Method | Passing Standard |
|---|---|---|---|
| Correctness | ... | ... | no regression, bug, compatibility, data, or security failure |
| Benefit | ... | ... | measured benefit meets target or explicitly documented threshold |
| Observability | ... | ... | key states, success, failure, and failure reason are visible in logs, traces, metrics, or audit events |
#### Exit Criteria#### Review Plan#### Risks And Fallback
| Risk | Impact | Trigger Signal | Mitigation | Fallback |
|---|---|---|---|---|
#### Gate To Next Phase
| Gate Condition | Verification Evidence | Completion Status | User Approval Required | Proceed Decision |
|---|---|---|---|---|
| ... | evidence available before next phase starts | complete / incomplete / blocked | no / yes with residual risk | proceed / pause |
Common phases are Discovery, Design, Foundation, Implementation, Integration,
Validation, Release, and Post-release Cleanup. Merge phases for simple work,
but do not skip Discovery, Validation, Release, or Rollback for high-risk work.
7. Add Review And Evidence Gates
Every phase gate must state what evidence proves the phase can close:
required tests and exact pass criteria
phase-local evidence that closes the phase without relying on future-phase
implementation, rollout, metrics, or cleanup
benefit tests proving the target outcome improved, not only that the code
avoids bugs
plan-to-code completeness rows showing code landed in production paths, not
only protocols, definitions, scaffolding, mocks, fake data, or demo scripts
logging evidence showing the affected chain's key states, success, failure,
and failure reasons are observable through logs, traces, metrics, or audit
events
required code, design, security, release, or data review
unresolved P0/P1 issues
risk mitigations and fallback readiness
artifacts to archive, such as scripts, dashboards, runbooks, or review notes
an explicit proceed / pause decision
For production-impacting work, also require rollback rehearsal or rollback
verification, monitoring and alerting, feature flag readiness when applicable,
and post-release observation windows.
If the current phase is not fully complete, record the missing evidence,
residual risk, and user approval status. Without explicit user approval, the
correct next action is pause, not continuing to the next phase.
8. Review Existing Plans
When reviewing an existing plan, lead with findings:
missing or weak problem definition
goals that cannot be measured
missing non-goals or scope controls
phases without gates or evidence
phase gates that depend on later phases or cannot be verified independently
phase transitions that proceed without 100% completion or explicit user
approval for residual risk
risks without triggers or fallback
production changes without rollout, rollback, or observability
data changes without idempotency, validation, or compensation
security changes without permission, audit, or abuse-case review
invented or unsupported project facts
Then provide a compact corrected outline or rewritten plan section if useful.
Output Quality Checklist
Before final output, verify:
Background and problem definition are clear.
Goals are measurable and non-goals control scope.
Goals state expected benefits, not only deliverables.
Facts, assumptions, constraints, risks, and open questions are separated.
Complexity and plan depth are justified.
Work is divided into progressive phases.
Each phase is independently verifiable and has no inverted dependency on
later phases.
Each phase has entry criteria, checks, tasks, deliverables, validation,
exit criteria, review plan, risks, fallback, and next gate.
Each phase gate requires 100% completion or explicit user approval with
recorded residual risk before proceeding; otherwise the plan pauses.
High-risk unknowns are investigated early.
Risks include trigger signals and mitigations.
Tests and validation have passing standards.
Validation separates correctness tests from benefit tests.
Benefit validation states baseline, target, measurement method, data
source, observation window, and pass/fail threshold when relevant.
