@runfusion/fusion 0.73.0-beta.2 → 0.73.0-beta.4

package/dist/plugins/.fusion-ce-skills/ce-plan/references/plan-sections.md

@@ -0,0 +1,405 @@
+# 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:
+
+- **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, conditionals, and exact
+thresholds verbatim. Economy targets the connective tissue around them, 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.