feat: ce-plan U-IDs and origin traceability loop
Close the brainstorm → plan → work traceability loop opened by PR #629. PR #629 added stable IDs (`A`, `F`, `AE`) and a Deep-product tier with a split Scope Boundaries section to `ce-brainstorm` requirements docs, and lightly updated `ce-plan` and `ce-work` to *carry forward* those IDs as constraints. But the plan template itself was never updated to expose the new origin IDs, and Implementation U
Overview
feat: ce-plan U-IDs and origin traceability loop
Overview
Close the brainstorm → plan → work traceability loop opened by PR #629. PR #629 added stable IDs (A, F, AE) and a Deep-product tier with a split Scope Boundaries section to ce-brainstorm requirements docs, and lightly updated ce-plan and ce-work to carry forward those IDs as constraints. But the plan template itself was never updated to expose the new origin IDs, and Implementation Units have no stable IDs of their own — so execution-side references like "blocked on Unit 3" remain ambiguous across edits, and origin actors/flows/acceptance examples are invisible to anyone reading the plan without opening the upstream brainstorm doc.
This PR completes the loop with five focused changes:
- Stable plan-local
U-IDsfor Implementation Units, with a stability rule that survives deepening reorders. - Conditional Origin Trace sub-blocks under Requirements Trace (Actors, Key Flows, Acceptance Examples) that appear only when the origin doc supplies them.
- Three-way Scope Boundaries split — triggered only at Deep-product origin — with the plan-local subsection renamed from the ambiguous "Deferred to Separate Tasks" to Deferred to Follow-Up Work.
- Sparse-by-design AE-link convention for test scenarios (
Covers AE2.) so Acceptance Example disambiguation propagates into enforcement. - Planning-side Alternatives rule mirroring brainstorm's: alternatives differ on how, not what.
Plus the supporting machinery: Phase 5.1 finalization checklist updates, deepening-workflow.md checklist updates (including a U-ID stability warning at the most likely renumber-accident vector), and synchronized updates to ce-work and ce-work-beta so U-IDs survive into execution as task-label prefixes and blocker/verification references.
Change Matrix
| File | Change | Unit |
|---|---|---|
plugins/compound-engineering/skills/ce-plan/SKILL.md | U-ID format + stability rule (Phase 3.3, 3.5, template) | U1 |
plugins/compound-engineering/skills/ce-plan/SKILL.md | Origin Trace sub-blocks + Scope Boundaries three-way split + rename to "Deferred to Follow-Up Work" | U2 |
plugins/compound-engineering/skills/ce-plan/SKILL.md | AE-link convention + Alternatives rule + Phase 5.1 checklist updates | U3 |
plugins/compound-engineering/skills/ce-plan/references/deepening-workflow.md | U-ID stability warning + origin A/F/AE preservation checks | U4 |
plugins/compound-engineering/skills/ce-work/SKILL.md + plugins/compound-engineering/skills/ce-work-beta/SKILL.md | U-ID recognition in blockers/verification + task label prefix rule | U5 |
Problem Frame
What's broken today
- Implementation Units have no stable identifier. The plan refers to "Unit 1, Unit 2…" — a positional label that renumbers when units are reordered or split.
ce-workandce-work-betawere updated by PR #629 to reference R/A/F/AE IDs in blockers and verification, but they cannot reference which unit is blocked unambiguously. Deepening (Phase 5.3) reorders or splits units, which is precisely when stability matters most. - Origin A/F/AE IDs are invisible in the plan output. The
ce-planSKILL.md text says to preserve origin A/F/AE as constraints implementation units must honor, but the plan template has no surface where they appear. An implementer or reviewer reading the plan must open the origin requirements doc to see which actors, flows, or acceptance examples the plan relates to. - Scope Boundaries cannot represent the product-tier distinction. PR #629 introduced
Deferred for later(product sequencing) vsOutside this product's identity(positioning rejection) at Deep-product brainstorms. The plan template has onlyDeferred to Separate Tasks, which is a different concept (PR-level implementation sequencing). Carrying forward an origin's product-tier scope split is currently impossible — and the existing name "Deferred to Separate Tasks" is itself ambiguous because "task" overlaps withTaskCreate/TaskListtooling and the section's contents are PRs/issues/repos, not tasks. - Acceptance Examples have no enforcement link. AE was added to the brainstorm precisely to disambiguate ambiguous requirements via canonical scenarios. Without a link from test scenarios to AE-IDs, the disambiguation decays — implementers can write tests that pass R3's literal text but miss the AE1 scenario that was supposed to pin down R3's meaning.
- Plan alternatives can re-litigate product questions. Without a planning-side mirror of brainstorm's "alternatives differ on what" rule, plans may regenerate product-shape alternatives (e.g., "should we build for end users or operators?") that should have been settled in brainstorm.
Design constraint that shapes every change
ce-plan must remain useful when no origin doc exists. Not every user runs ce-brainstorm first — piecemeal use is by design. Every origin-derived structure introduced here must be explicitly conditional in the template, with a stated fallback when origin is absent, and must not produce broken sections (empty headers, dangling references) in the no-origin path.
This is the conditionality design rule the PR also introduces.
Requirements Trace
Plan template structure
- R1. Implementation Units carry stable
U-IDsthat survive reordering, splitting, and deletion. New units take the next unused number; gaps are allowed; existing IDs are never renumbered. - R2. The plan template surfaces origin Actors/Key Flows/Acceptance Examples in a Requirements Trace sub-block when the origin doc supplies them, and omits the sub-block cleanly when origin is absent or non-Deep tier.
- R3. The plan template supports a three-way Scope Boundaries split at Deep-product origin (
Deferred for later+Outside this product's identity+Deferred to Follow-Up Work), and collapses to a single list when origin is absent or non-product-tier. - R4. The "Deferred to Separate Tasks" subsection is renamed to Deferred to Follow-Up Work wherever it appears in
ce-plan/SKILL.md, including Phase 5.1 review checklist references.
Workflow rules and conventions
- R5. Test scenarios that directly enforce an origin Acceptance Example prefix with
Covers AE.(orCovers F / AE.). The convention is sparse-by-design — most test scenarios are finer-grained than AEs and do not link. - R6. A planning-side Alternatives rule (Phase 4.1b) states: alternatives differ on how the work is built; tiny implementation variants belong in Key Technical Decisions; product-shape alternatives belong in
ce-brainstorm.
Review and deepening machinery
- R7. Phase 5.1 finalization checklist enforces the new contract using judgment-call phrasing ("origin R/F/AE that affects implementation"), not mechanical "every ID appears" checks. All origin-related checks are guarded by "if origin exists."
- R8.
deepening-workflow.mdchecklist gains explicit U-ID stability warning (deepening must NOT renumber units when reordering or splitting) and origin A/F/AE preservation checks.
Execution-side recognition
- R9.
ce-work/SKILL.mdandce-work-beta/SKILL.mdrecognizeU-IDalongsideR/A/F/AEin blockers, deferred-work notes, task summaries, and final verification. When creating tasks from plan units, task labels include the U-ID prefix (e.g., "U3: Add parser coverage") so blockers and summaries reference the same anchor.
Validation
- R10.
bun testandbun run release:validatepass after the change.
Success criteria
- A plan generated from a brainstorm with A/F/AE IDs surfaces those IDs in its Requirements Trace section without the implementer needing to open the origin doc.
- A plan generated from no upstream brainstorm renders a clean template with no empty origin-related headers or dangling references.
- A plan whose units get reordered during deepening retains its original U-IDs (e.g., U1, U3, U5 in their new order is acceptable; renumbering to U1, U2, U3 is not).
ce-workreferring to "U3" in a blocker can be unambiguously matched to a specific Implementation Unit in the source plan, regardless of plan edits since work began.- A test scenario that enforces AE1's canonical scenario carries
Covers AE1.so the disambiguation is auditable.
Scope Boundaries
- This PR does not introduce a new plan-depth tier. There is no "Deep-product-plan" classification. Lightweight / Standard / Deep remain.
- No new top-level template sections. Origin trace lives inside the existing Requirements Trace section.
- No new ID namespaces beyond
U. Open Questions do not gain Q-IDs. - No
Implementation Unitsrename. - No splitting of
ce-planinto multiple skills. - No fixed-category decision checklists (Programming language, Database, etc.) — wrong abstraction for
ce-plan's open-ended scope. - No source code, schema, or test changes. This is a skill-content (Markdown) PR. The only commands run are
bun testandbun run release:validatefor validation.
Deferred to Follow-Up Work
- A plan-section matrix (analogous to the brainstorm tier-by-section matrix from PR #629). Worth doing — current inclusion rules are scattered across Phase 3/4 — but standalone documentation cleanup, not part of the traceability loop.
- An "Existing Technology" detected callout in plan output, surfacing what the plan inherits vs introduces.
- A "Deferred Decisions" table with a "when to revisit" column.
- A
docs/solutions/write-up capturing the U-ID/R-ID/AE-link traceability convention. Per repo convention these are written after the change ships, so this belongs in a follow-upce-compoundpass once this PR merges.
Context & Research
Relevant Code and Patterns
plugins/compound-engineering/skills/ce-brainstorm/references/requirements-capture.md— PR #629's section matrix and triggered-section format establish the template-author conventions (R/A/F/AE prefix style,Covers:back-references, conditional sections). The plan-side changes mirror these conventions verbatim.plugins/compound-engineering/skills/ce-brainstorm/SKILL.md— Phase 0.3's Deep-product detection logic is the upstream signal that triggers the three-way Scope Boundaries split in the plan template.plugins/compound-engineering/skills/ce-plan/SKILL.md— Phase 0.3 already has placeholder text about preserving A/F/AE IDs and the Scope Boundaries subsections. This PR completes the work by making them visible in the plan output.plugins/compound-engineering/skills/ce-work/SKILL.mdline 297 +ce-work-beta/SKILL.mdline 362 — the existing R/A/F/AE recognition guidance in "Track Progress" sections is the seam where U-ID is added.
Institutional Learnings
docs/solutions/skill-design/research-agent-pipeline-separation-2026-04-05.md— confirms the brainstorm/plan/work pipeline is intentionally separated by information type, with the plan as the sole handoff artifact to ce-work. This grounds the conditionality design rule: ce-work must read everything it needs from the plan file alone, so U-IDs must live in the plan, not require reading back into the brainstorm.docs/solutions/skill-design/beta-skills-framework.mdanddocs/solutions/skill-design/beta-promotion-orchestration-contract.md— confirm that ce-work and ce-work-beta must stay in sync atomically when the contract changes. The U-ID recognition guidance applies equally to both surfaces; sync decision must be stated explicitly per repo convention.docs/solutions/best-practices/conditional-visual-aids-in-generated-documents-2026-03-29.md— establishes that conditional document sections must trigger on observable content patterns, not size/depth/tier proxies. Validates the "trigger on origin doc presence" model for Origin Trace sub-blocks rather than "trigger on plan tier."docs/solutions/best-practices/ce-pipeline-end-to-end-learnings-2026-04-17.md— flags that doc-review reliably catches "unit adds a thing the plan's own scope boundary forbade." The Scope Boundaries three-way split is exactly the kind of architectural template change doc-review should catch contradictions in. Also reinforces: never conflate two semantic meanings in one identifier — keep U-ID and R-ID semantics crisp.docs/solutions/skill-design/ce-doc-review-calibration-patterns-2026-04-19.md— "Coverage/rendering count invariants need a single source of truth." Applies to U-ID generation: the Implementation Unit heading is the authoritative location; ce-work's blocker/verification recognition reads, never coins.
External References
- None used. This is a skill-content change to in-repo Markdown; no external docs or framework behavior was consulted.
Key Technical Decisions
- U-ID format mirrors R/A/F/AE exactly. Plain prefix at start of bullet (
U1.), not bolded. The unit's heading line becomes- [ ] U1. **Name**so the checkbox, ID, and name are all visible on one line. Rationale: PR #629 chose this format deliberately for visual distinctiveness without table or bold-label overhead. Diverging would create asymmetry across the four ID namespaces an implementer reads back-to-back. - U-IDs are plan-local, not session-global. Each plan numbers its own units starting at U1. No cross-plan uniqueness is required because no downstream consumer references units across plans. Plan-local scope keeps the namespace simple and avoids coordination problems.
- U-ID stability rule lives in two places: Phase 3.5 (where units are defined) AND template comments (Phase 4.2). Deepening (Phase 5.3) is the most likely accidental-renumber vector — an agent reorganizing units may "tidy up" the numbering. Stating the rule in two places — once where new units are minted, once visible in the template the agent is editing — defends against the accident at both entry points.
- Origin Trace is a sub-block under existing Requirements Trace, not a new top-level section. A new top-level
## Originsection is cleaner in theory but adds a header that disappears in no-origin mode and creates ceremony for the common case. Sub-blocks keep the section count flat and let the section degrade naturally. - Scope Boundaries three-way split triggers on observable origin content (presence of
Outside this product's identitysubsection in origin), not on a "Deep-product origin" tier flag. This avoids requiring the plan to know the origin's tier classification — it just inspects what the origin doc actually contains. Aligned withconditional-visual-aids-in-generated-documents-2026-03-29.md. - Renamed "Deferred to Separate Tasks" → "Deferred to Follow-Up Work." Three reasons: "task" overlaps with
TaskCreate/TaskListtooling; the section's contents are PRs/issues/repos (not "tasks"); and "Out of Scope for This Plan" (an alternat