compound-engineering-plugin-mirror/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 — the decisions everything else rests on 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 decisions everything else rests on 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.

A section belongs only when it serves 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 planning stages, 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.
• 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.

Determine whether a plan can be executed from its contents. The Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done must give the executor enough direction, with no launch-blocking question remaining. Mark open questions as blocking or deferred; deferred implementation details do not prevent work. A Product Contract without sufficient planning needs enrichment.

Do not write a readiness or execution-status field. When updating an older artifact, remove artifact_readiness from its frontmatter or visible HTML metadata. An old readiness label does not establish completeness or override a blocker. Plans carry no status field and no mutable execution lifecycle.

Approach-plans, answer-seeking outputs, and universal-planning outputs remain outside this software implementation contract unless they contain the full contract above. Route non-code deliverables by their contents and execution: knowledge-work.

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 (outcome), Means (chosen approach), 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.

Whether a plan file is warranted

SKILL.md's Output Contract gate decides this at intake, before any research: Direct and Chat brief results stay in chat (references/output-contracts.md); a Durable run writes the file this reference describes.

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, means (only when an approach is fixed), authority hierarchy, stop conditions, execution profile, and who finishes and ships the work. This is the fastest way for an executor to avoid drifting from the plan. A reader who has not read the rest of the plan must be able to hold the Objective as the goal. Remaining-true constraints live on their owning R-IDs (the R-IDs that state them), not as extra Objective clauses — user-checkable is not a license to pack them onto the Objective. An Objective that is only understandable after later sections is not yet the Objective, even when a user could check the outcome and a different implementation would still serve it. The Objective is always the outcome: what is true for users or operators afterwards, phrased so it would still read as the goal under a different implementation. It sits outside the component being changed, which is a question of who can check it rather than of which nouns it uses: an outcome someone outside that component can verify without knowing its internals is an Objective even when that component is what changed, and one only its internals can settle is not the Objective however outcome-shaped its wording; the registry above decides where it does belong. The usual failure is an objective about the component's own execution — the wall-clock it no longer holds, the runtime it no longer consumes, what stays isolated inside it — which only its internals settle. Infrastructure and refactor work has such an objective too: the reason that component's behavior mattered to someone. The chosen approach is the Means, its own line whenever the request or the plan has fixed one — never invented for outcome-only work. It is a linked projection under the one-owner rule below: one line naming the approach and citing the KTD or Key Decision that owns it (Means: … (KTD2)), never a restatement of that owner's mechanism. Test: if the implementation changed, would the Objective still be the goal, and could a reader who does not know the changed component's internals tell whether it was met? No to the first makes it a Means. No to the second means it is stated at the component's level, and the Objective is whatever depended on that component. When a request supplies only its approach ("move X out of A into B"), that is the Means; the Objective is the outcome it serves, derived from the request's motivation, the project's stated problem, or asked for — never the approach restated.
• 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.

The first five entries below carry the Product Contract's product framing — what is being built and why. Later entries mix Product Contract subsections (Scope Boundaries, Open Questions, Acceptance Examples, Sources) with Planning Contract ones; the hard floor above remains authoritative for which section sits under which contract. Problem Frame is unconditional; each of the other four is included when its own test says so. A plan that skips all four conditional framing entries has usually inherited its framing from an upstream Product Contract — check before concluding none of them apply.

• Problem Frame — the hard floor above contains it unconditionally, so this entry governs its depth, never whether to include it. Give it paragraphs when motivation isn't obvious from Summary alone; keep it to a line or two when the motivation was settled upstream and more would only echo the origin document. Backward-looking / situational. Does NOT restate the proposal; the remedy lives in Summary.

• Key Decisions — include when the plan carries product-level choices that constrain the Requirements below, whether made during planning (scope narrowings, defaults chosen against a real alternative, framing the user picked) or inherited from an upstream Product Contract, which Phase 0.3 requires carrying forward with its rationale. Each entry is a provenance index entry, not a second statement of the rule: the decision in bold, at most one line of rationale, and exact Governs R5, R7 links when it constrains specific requirements. The normative text lives on the governed Rs. Session-settled annotations follow the rules under "ID and content rules" below. Distinct from Planning Contract's Key Technical Decisions, which record how-level choices; a product decision belongs here, and a KTD cites it rather than mirroring it. Skip only when no such choice exists on any side: every requirement follows directly from the request, any upstream Product Contract weighed no alternatives, and the session settled none. A session-settled: decision always keeps the section — plan-write and the routing table both require its labeled entry to live here.

• Success Criteria — include when there are quality / metric / handoff signals that Requirements don't already carry: quantitative metrics ("p95 latency under 200ms"), qualitative criteria ("the agent's output reads as one voice"), process / handoff quality ("ce-doc-review can act on this without follow-ups"). Skip when Requirements ARE the success criteria (every R is "done when the R is true"). Requirements that describe an approach rather than an outcome are not success criteria; then include at least one criterion that would show the Goal Capsule Objective was reached.

• Actors — include when the work has multi-party behavior (multiple humans, agents, or systems meaningfully involved) that the units must honor. Skip for single-actor work and for plans whose change is internal to one component — most implementation plans skip this.

• Key Flows — include when the work has multi-step behavior whose sequencing the units must preserve. Skip when the change is not flow-shaped, or when Requirements and Acceptance Examples together already prevent downstream invention of paths — again, most implementation plans skip this.

• 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 characteristics, 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 — include the research that orients the implementer or justifies the choices the plan rests on. The test: "if I were the implementer reading this cold, would this breadcrumb help me make better choices?" Yes → include (code locations like services/convex/reports.ts:174-176, external docs, RFCs, constraints, prior plans — the category is inclusive, not enumerated). A record of the planning process itself (reading the user's prompt, glancing at obvious entry points, restating prose) → omit. Put it inline next to the KTD or unit it justifies, or in a dedicated section — both shapes work. A constraint adopted from a Compound Pack file is cited inline as (pack: <id>, <path within the pack>) after the requirement, KTD, constraint, or risk it shaped. The path is relative to the pack's own directory, so it is stable for path- and git-sourced packs alike. Cite the pack text; do not restate it. That marker is reserved for pack files; <root>/solutions/ learnings keep the ordinary path citation, so a reader can tell a prescriptive pack rule from a retrospective learning.

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 — legacy and non-unified plans only. Any ce-unified-plan/v1 artifact keeps both headings regardless of plan depth: the hard floor names them separately and downstream consumers anchor on them. (Scoped by artifact contract, not by depth — a Lightweight plan can still be implementation-ready.)
• 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.

Write every kept section through the ce-noslop skill.

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.
• A Summary is a handful of sentences, not one sentence with five semicolons and four parentheticals. A KTD's rationale is the reason that decided it, 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.

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.

One owner per rule; cite, don't restate. A normative rule — a gate, cap, threshold, protocol, or output contract — is stated in full at exactly one owning entry: product behavior on its R-ID; an implementation choice on its KTD. Every other layer cites the owning ID and adds only what is local to it — a unit's Approach carries unit-local deltas (files, sequencing, patterns), never a re-derivation of the protocol its cited Rs and KTDs own. Linked projections are allowed (an AE restating behavior under Covers R…, a Flow citing the Rs it sequences). Unlinked sibling restatement — the same rule written out again in a KTD, Scope bullet, or Approach with no ID link — is the defect: each copy drifts independently. When linked layers disagree, authority is typed: the R wins on product behavior; the KTD wins on implementation mechanism within its cited R constraints; a unit overrides neither; AEs and Flows illustrate and sequence, never amend.

Bind external authorities; don't summarize them. When a requirement, KTD, or unit adopts an external document (a field guide, spec, standard), state the commitment, cite the path, and record only this work's deltas. A multi-sentence summary of the cited document is restatement of an owner that lives outside the doc.

Named test, run before the plan is declared written: could the implementer find a contradiction in each section in one pass? Could a colleague who was not in the session say what this work is after the Objective alone? A sentence carrying more than one parenthetical, a sentence chaining more than two semicolons, an item specifying two outcomes, or a rule stated in full in more than one section fails the test — split it (a semicolon chain becomes a list), defer it, or replace the duplicate with its owning ID.

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 planning stages (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), KTD-IDs (Key Technical Decisions, implementation-ready plans), A-IDs (if the plan has Actors), F-IDs (if it has Flows), AE-IDs (if it has Acceptance Examples). IDs are stable across plan revisions — never renumber to "clean up gaps."
• Plain prefix. R1., U1., KTD1. as bullet prefixes. Do not bold; the prefix is visually distinctive on its own.
• KTD-IDs on implementation-ready plans. Number Key Technical Decisions (KTD1., next unused number, same never-renumber rule as U-IDs) in newly authored implementation-ready plans, and in an existing plan whenever a KTD is added, split, or first cited by a unit. Untouched unnumbered KTDs in legacy plans stay as they are — readable by label, no mass renumbering.
• Repo-relative paths. Always. Never absolute paths in plan content; they break portability across machines, worktrees, teammates.
• No record of the planning process. 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.
• Session-settled annotations on KTDs. A Key Technical Decision that records a decision settled in the invoking conversation carries an inline annotation on its entry: (session-settled: user-directed — chosen over <alternative>: <one-line reason>). Exactly two classes: user-directed (the user chose against or between surfaced options) and user-approved (the agent proposed with the tradeoff surfaced; the user assented). An agent never labels its own unexamined proposal. A KTD that makes the how-level choice instantiating a labeled Product Contract Key Decision inherits the label and cites the decision's governed R-IDs. Do not create a KTD that merely mirrors a Product Key Decision with no new technical choice — the Key Decision plus its Governs R… links already own that content. The annotation is self-contained — decision, rejected alternative, and one-line reason readable without the conversation — and lives inline on the entry: no sidecar files, no frontmatter registry, no numeric weights, no lifecycle field. Like a (see origin: <path>) citation, it is decision provenance, not a record of the planning process — review passes must not strip it. A consumer that does not recognize the annotation treats the entry as a normal KTD.
• 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.