everyinc--compound-engineering-plugin/skills/ce-plan/references/plan-sections.md

Plan Sections

This reference describes what makes a great implementation plan. It does NOT prescribe how the plan looks on the page — rendering is handled by the format-specific references (markdown-rendering.md, html-rendering.md).

The outcome

A great plan enables three audiences to act:

• The implementing agent (ce-work or a human) starts from an informed baseline — load-bearing decisions are named, research breadcrumbs orient their own investigation, unit boundaries are clear. The plan gives the implementer a starting point, not a substitute for their own investigation.
• The reviewer identifies the load-bearing decisions and the boundaries of what's being changed in one pass.
• The future reader (anyone returning months later) traces why the work was done, what shaped it, and where the artifacts live.

Sections earn their place by serving one of these audiences. Omit padding.

Unified plan artifact contract

ce-plan writes the canonical compound-engineering plan artifact. The same artifact may begin as a requirements-only skeleton from ce-brainstorm and later be enriched by ce-plan; it is still one plan file moving through readiness states, not a requirements doc plus a separate implementation doc.

When the artifact is meant to be consumed by implementation agents, use:

• artifact_contract: ce-unified-plan/v1 — declares this contract.
• artifact_readiness — document completeness, not work progress. Valid values are:
  • requirements-only — Product Contract exists; planning sections are not complete and the artifact is not executable.
  • implementation-ready — Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done are complete enough for ce-work, /goal, or an equivalent executor, and no launch-blocking open question remains. A plan that is otherwise complete but still has a blocking product/architecture question stays requirements-only, so the next step it routes to is blocker resolution / planning, not implementation. Deferred (non-blocking) questions do not hold readiness back — mark each open question as blocking or deferred so this distinction is explicit.
• product_contract_source — where the Product Contract came from: ce-brainstorm, ce-plan-bootstrap, legacy-requirements, or another explicit source string when a repo has a specialized producer.
• execution — code for implementation plans, knowledge-work for non-code deliverables. Absence remains legacy-compatible and means code only for older plans without artifact_contract.

Do not use progress-like readiness values such as active, in_progress, completed, or done. Readiness answers "can the artifact be executed?", not "has execution happened?" Plans still carry no status field and no mutable execution lifecycle.

Do not use artifact_readiness: approach-plan. Approach-plans, answer-seeking outputs, and universal-planning outputs are outside this software implementation artifact contract unless they include the full Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done required for software execution. Route those artifacts by their own shape or by execution: knowledge-work, not by adding a third unified readiness value.

Section ID Registry

Unified artifacts use these stable logical sections. Markdown uses the heading text; HTML uses matching visible headings and anchor IDs. Downstream skills grep or anchor-scan for these names before reading large bodies.

Logical section	Markdown heading	HTML id	Reader use
Goal Capsule	## Goal Capsule	goal-capsule	Objective, authority hierarchy, and stop conditions
Product Contract	## Product Contract	product-contract	Requirements, actors, flows, acceptance examples, product scope
Product Requirements	### Requirements under Product Contract	product-requirements	Requirement extraction for review and implementation trace
Planning Contract	## Planning Contract	planning-contract	KTDs, technical design, assumptions, sequencing
Implementation Units	## Implementation Units	implementation-units	U-ID work packets for execution
Verification Contract	## Verification Contract	verification-contract	Repo-specific test commands and quality gates
Definition of Done	## Definition of Done	definition-of-done	Global and per-unit completion criteria
Appendix	## Appendix	appendix	Long research, raw notes, or supporting detail

Requirements-only artifacts are kept light: a Goal Capsule and the Product Contract. They must not point implementers at absent Planning Contract, Implementation Units, Verification Contract, or Definition of Done sections. ce-plan adds those implementation sections when it enriches to implementation-ready. Implementation-ready artifacts include the full registry above, except Appendix remains optional.

Wayfinding: map before reading (size-aware)

The document does not carry a reading guide; consuming skills own the reading algorithm. A short plan — a lightweight or requirements-only artifact that fits in a screen or two — can just be read in full; that is cheaper and simpler than scanning and ranging. But an implementation-ready unified plan is often long, and HTML output (also supported) is more verbose still, so for anything beyond short, do not load the entire artifact to find your way around. Build a section map first, then read only the ranges the task needs:

• Markdown: scan headings to get the section and unit map — e.g. rg -n '^#{1,3} ' <plan> (top-level sections plus ### U<N>. units).
• HTML: scan the heading elements (<h1>–<h3>) and their anchor ids; match on the section name and ignore the wrapper tags.

In both formats the section names and anchor ids are the stable contract from the Section ID Registry above (Goal Capsule/goal-capsule, Verification Contract/verification-contract, ### U<N>. units, …). Wayfind against those registry names, not a brittle tag/format pattern, so the instruction survives rendering changes. After mapping, read metadata, then only the sections the task needs — e.g. Goal Capsule, the active U-ID plus its cited R/F/AE/KTD, Verification Contract, and Definition of Done. Read the Appendix or unrelated units only when a section you are already reading cites them.

Decide whether a plan doc is warranted at all

Not every invocation of ce-plan should produce a plan document. For genuinely atomic work, the doc is ceremony — the implementer (whether ce-work or a human) can act directly without IDed units, KTDs, or Requirements as a checklist.

Bias toward producing a plan. The risk asymmetry favors writing one: a thin plan doc for small work is mild ceremony, but skipping a plan when one was warranted costs the implementer real time (reinvented decisions, lost unit boundaries, no IDed requirements to verify against). When unsure, write the plan.

Skip implementation-ready plan creation only when ALL of these hold:

• The work is atomic — fits in one commit, no meaningful unit boundaries to break out independently.
• There are no design choices that constrain implementation — no Key Technical Decisions worth recording. If the work needs the implementer to make a choice between two approaches, those approaches are KTDs and a plan is warranted.
• There are no scope boundaries worth pinning in writing — the work scope is self-evident from the user's request.
• No upstream artifact (a brainstorm with R-IDs, an incident report, a deferred-follow-up item from a prior plan) needs traceability through this plan.

Stress test the "looks atomic" case. Many requests look atomic at first glance but hide design decisions:

• "Add caching to this endpoint" — sounds atomic, but TTL, invalidation, cache key shape, and backend selection are all KTDs. Write the plan.
• "Migrate from package A to package B" — sounds mechanical, but semantic differences between the packages create migration KTDs. Write the plan.
• "Add rate limiting" — sounds small, but algorithm, scope, and configurability are all KTDs. Write the plan.

vs. genuine skip cases:

• "Fix typo in README line 47" — atomic, no KTDs, skip the plan.
• "Rename oldFn to newFn across the repo" — mechanical, no design choices, skip the plan.
• "Bump dependency X to v2.3.1" — mechanical, skip the plan (unless the bump introduces breaking changes that warrant unit-by-unit migration).

When skipping the plan doc, the work proceeds directly to ce-work or to implementation, and any decisions made along the way land in the commit message or docs/solutions/ if they're worth carrying forward.

Implementation-ready hard floor

When an implementation-ready software plan is warranted, these sections are present. They carry the contracts downstream consumers depend on.

• Goal Capsule — objective, authority hierarchy, stop conditions, execution profile, and tail ownership. This is the fastest way for an executor to avoid drifting from the plan.
• Product Contract — product scope and behavior. Contains Summary, Problem Frame, Requirements with stable R-IDs, and any material Actors, Flows, Acceptance Examples, Success Criteria, Scope Boundaries, Dependencies, Outstanding Questions, and Sources. This replaces the separate requirements artifact in new brainstorm-to-plan flows.
• Planning Contract — the implementation-facing decisions: Key Technical Decisions, high-level design, assumptions, implementation constraints, sequencing, and research that shapes how the Product Contract will be built.
• Implementation Units (with stable U-IDs) — discrete work packets sized so each is independently executable. Each unit names Goal, Requirements, Files, Approach, Test Scenarios, and Verification. ce-work and goal-mode executors consume these units.
  • Unit Index (large plans only, ~10+ units). When the plan has roughly ten or more units, open the section with a compact navigation table — one row per unit: U-ID · one-line title · files touched · depends-on. It lets an executor map units to files and resolve dependency order without scanning every unit body. It is a navigation aid only: the unit bodies stay authoritative, it carries nothing beyond those four fields (no approach, tests, or rationale), and files touched is the key/primary paths, not an exhaustive restatement. Omit it below ~10 units — there the per-unit Dependencies/Files (and any sequencing or dependency diagram) already suffice, and an index would be ceremony.
• Verification Contract — repo-specific commands and quality gates, including which tests prove the plan, when release:validate applies, and what behavioral skill evaluation is required. Avoid generic "run tests" language when the repo has concrete commands. When the goal is optimization-shaped (build time, latency, coverage, bundle size), express a measurable threshold as the exit criterion (e.g., "p95 latency < 200ms", "build time reduced 30%") and consider routing to ce-optimize — a metric target is a sharper done signal for a long-running goal than a boolean check.
• Definition of Done — global and per-unit done criteria. This is the completion contract for /goal or equivalent long-running workflows. Include a cleanup criterion: a long autonomous run accumulates dead-end and experimental code from approaches that did not pan out; declaring done requires that abandoned-attempt code is removed, not left in the diff.

Include when material

These sections are present when they carry information that isn't covered elsewhere. The test is not "is this a substantial plan?" — it is "does this specific plan have content this section would surface?" Filling a section with placeholder prose is worse than omitting it.

• High-Level Technical Design — include when the technical approach has shape that prose alone doesn't carry well: architecture across components, sequencing across processes, state machines, branching gates. Visualizations (component topology, sequence, swim lane, flowchart, data-flow) typically live here. Skip when the approach is a one-paragraph pattern application that the prose itself conveys.

• Scope Boundaries — include when scope is contested, when there are tempting non-goals worth naming explicitly, or when "deferred for later" needs distinguishing from "outside the product's identity." Skip when scope is obvious from Requirements alone.

• Open Questions — include when there are genuinely unresolved items that block planning or implementation. Skip when the plan is complete; an empty "Open Questions: none" section signals false uncertainty.

• System-Wide Impact — include when the change affects cross-cutting concerns (data lifecycles, auth boundaries, performance posture, cardinal rules, shared infrastructure, agent/tool parity, prompt context, shared workspaces). Skip for changes localized to one component where the impact is self-evident.

• Risks & Dependencies — include when there are real risks worth flagging (external service changes, version pins under churn, behavioral assumptions worth highlighting) or material upstream dependencies. Skip for low-risk localized work.

• Acceptance Examples — include when any requirement has a state-dependent or conditional shape ("When X, Y") where the prose alone leaves ambiguity about edge cases. Skip when all requirements are unconditional and unambiguous.

• Documentation / Operational Notes — include when documentation, monitoring, runbooks, or rollout steps need explicit notes. Skip when the work is purely internal and uses existing operational scaffolding without modification.

• Sources / Research — surface the research that orients the implementer or justifies load-bearing choices. The test: "if I were the implementer reading this cold, would this breadcrumb help me make better choices?" Yes → surface (code locations like services/convex/reports.ts:174-176, external docs, RFCs, constraints, prior plans — the category is inclusive, not enumerated). Process exhaust (reading the user's prompt, glancing at obvious entry points, restating prose) → omit. Surface inline next to the KTD or unit it justifies, or as a dedicated section — both shapes work.

Agent agency

The catalog is a floor, not a ceiling. When the plan's content doesn't fit any catalog section, introduce a new one — don't force the content into a section it doesn't belong in. Content drives section choices, not vice versa.

The agent also picks per artifact:

• Whether Problem Frame merges into Summary
• Sub-groupings (Requirements by capability, KTDs by component, Units phased into milestones)
• How much detail each section carries
• Whether HTD has one diagram, several, or none — and whether visualizations live in HTD or embedded in other sections

Prose economy

"Include when material" sizes which sections appear; this sizes how the kept prose reads. A section can be material and still be written loosely — the failure mode is a material section padded into a wall of text where contradictions hide and the implementing agent loses the thread. A deep plan earns length through coverage (more units, more traced requirements, real risks), never through wordiness around that coverage.

Hold every kept section to these:

• Lead with the decision or outcome. Put the conclusion first, then the reason, then background; keep one claim plus its support per paragraph. Don't bury a Key Technical Decision, the chosen scope, an open blocker, or a unit goal beneath its rationale. This does not override section roles — Summary stays proposal-only, Problem Frame stays motivation-only and never restates the remedy.
• One idea per sentence. A Summary is a handful of sentences, not one sentence with five semicolons and four parentheticals. A KTD's rationale is the load-bearing reason, not every reason.
• A requirement or unit is one sentence of intent plus at most one qualifier. When it would specify two outcomes ("either A or B, the implementer decides"), state the intent and send the fork to Open Questions — don't write both arms in full inside the item.
• Cut hedges and intensifiers. "Critically", "deliberately", "explicitly", "genuinely", "actually", "simply" carry nothing the implementer acts on.
• Prefer the verb to the nominalization. "Demote the grid", not "the demotion of the grid is the deliberate change in this plan".

Precision is not padding: keep file paths, IDs, dates, domain terms, conditionals, and exact thresholds verbatim; when a concrete anchor is knowable from the work already done, use it instead of a vague abstraction. Economy targets the connective tissue around precision, never the precision itself.

Resolve in place; don't stratify. When deepening, a doc-review pass, or a later decision supersedes earlier text, rewrite or remove the original — don't leave it standing as strikethrough or stack a separate "resolutions" layer on top of it. Version control holds the history. Stacked strata double the reading surface and hide which text is live.

Named test, run before the plan is declared written: could the implementer find a contradiction in each section in one pass? A sentence carrying more than one parenthetical, or an item specifying two outcomes, fails the test — split it or defer it.

Plan metadata fields

Every plan carries a small set of stable metadata fields that downstream tooling depends on. The contract is format-independent: in markdown these fields appear as YAML frontmatter at the top of the file; in HTML they appear as visible header text (typically a <dl> of <dt>/<dd> pairs or a stats strip). Field names and semantics are the same across both formats so consumers can locate them without knowing which format produced the plan.

Required

• title — the plan's descriptive name with a - Plan suffix (e.g., Highlighter Tool - Plan), matching the H1 (markdown) or document <h1> (HTML) so file metadata and visible heading don't drift. Stable across readiness states (it is a plan at every stage). Do not put a conventional-commit prefix (feat:/fix:) in the title — the type field carries that classification.
• type — conventional-commit-prefix-aligned classification (feat, fix, refactor, chore, docs, perf, test, etc.). Carries the intent the eventual commit message should reflect.
• date — creation date in ISO 8601 (YYYY-MM-DD), ASCII digits only.

Plans carry no status field — a plan is a decision artifact, not a tracked work item. ce-work does not mutate the plan at ship time; whether a plan shipped is derived from git, not stored in the doc. Do not add a status field or an active → completed lifecycle.

Optional but well-known

These fields are not required, but when set they have fixed names and semantics so downstream tooling can rely on them:

• origin — repo-relative path to an upstream brainstorm requirements doc (e.g., docs/brainstorms/2026-05-12-pagination-requirements.md). Set when planning from an upstream brainstorm; carried for traceability and re-resolved when ce-plan re-deepens.
• deepened — ISO 8601 date marking the first time the confidence check substantively strengthened the plan. Presence affects Phase 0.1 resume fast-path logic (see references/deepening-workflow.md).
• execution — execution domain for downstream routing: code (the default when absent) or knowledge-work. ce-work's input triage reads this: a plan marked execution: knowledge-work routes to the non-code carve-out (read sources, synthesize, produce a deliverable — skipping the branch/test/commit/CI lifecycle); absent or code routes to the normal code path. Written by ce-plan's approach-altitude flow (references/approach-altitude.md) when a non-code deliverable is persisted for execution.

Field names are stable across plan revisions — never rename a field or repurpose its semantics. Agents composing new plans MUST use these exact names; adding new fields is fine, but renaming origin to source or date to created breaks the downstream consumers above.

ID and content rules

These apply regardless of rendering format.

• Stable IDs. R-IDs (Requirements), U-IDs (Implementation Units), A-IDs (if Actors fire), F-IDs (if Flows fire), AE-IDs (if Acceptance Examples fire). IDs are stable across plan revisions — never renumber to "clean up gaps."
• Plain prefix. R1., U1. as bullet prefixes. Do not bold; the prefix is visually distinctive on its own.
• Repo-relative paths. Always. Never absolute paths in plan content; they break portability across machines, worktrees, teammates.
• No process exhaust. No "captured at Phase X" notes, no ## Next Steps pointing to the next skill, no italic provenance lines. Engineering process metadata belongs in commit messages and tool output, not the artifact.
• Group Requirements by concern when they span distinct logical areas. The trigger is distinct concerns, not item count — even four requirements benefit from grouping if they cover three different topics. Skip grouping only when all requirements are genuinely about the same thing; a long flat list is a smell that subgroups were missed. Group by capability (e.g., "Packaging", "Migration and compatibility", "Contributor workflow"), not by the order requirements were discussed. R-IDs stay continuous across groups (R1, R2 in the first group; R3, R4 in the second; never restart at R1 per group).

Rendering

The format-specific references describe how to render these sections in each output format:

• Markdown rendering: references/markdown-rendering.md
• HTML rendering: references/html-rendering.md

This reference (plan-sections.md) is about WHAT the plan contains; rendering references are about HOW each format presents it. The plan is written in one format — markdown OR HTML, never both — based on the resolved output mode. The section catalog is the same regardless of format.