Ideation Sections

This is the section contract for the ce-ideate artifact — it describes what a persisted ideation document contains, independent of output format. It is paired with a format-rendering reference (references/markdown-rendering.md or references/html-rendering.md) that describes how the resolved format presents these sections. The same content renders in either format; only presentation differs.

Load this file at save time alongside the rendering reference matching OUTPUT_FORMAT (see references/post-ideation-workflow.md §4.1).

What the artifact contains

An ideation artifact is a ranked, critiqued candidate set, the grounding the candidates were qualified against, and a record of what was cut. It is a human-facing discovery document, not a requirements doc or plan — keep it about the ideas and their basis, not implementation.

Metadata

date — composition date (YYYY-MM-DD).
topic — kebab-case topic slug.
focus — the focus hint, when one was given. Omit when open-ended.
mode — repo-grounded, elsewhere-software, or elsewhere-non-software.

Markdown renders metadata as YAML frontmatter at the top of the file. HTML renders it as visible header text (per the html-rendering hard invariant: one visible source of truth per value, no hidden machine-readable copy).

No status field — not on the doc, not per idea. An ideation doc is a point-in-time discovery artifact, not a tracked work item: it carries no active → completed lifecycle and no per-idea "explored" marker. Tracking mutable workflow progress inside the artifact would create a second source of truth that drifts — whether an idea was later pursued is knowable from downstream artifacts (a brainstorm or plan that picked it up), so it is not duplicated here.

Grounding Context

The Phase 1 grounding summary the ideas were qualified against — labeled "Codebase Context" in repo mode, "Topic Context" in elsewhere mode.

Topic Axes (conditional)

The 3-5 axes from Phase 1.5, one per line. When Phase 1.5 was skipped, a single line records why (Decomposition skipped — atomic subject or Decomposition skipped — surprise-me mode). Omit the section entirely when not applicable.

Ranked Ideas

The surviving candidates, ranked. Each idea carries:

title
description — concrete explanation.
axis — the topic axis this idea targets. Omit when decomposition was skipped.
basis — tagged direct: (quoted evidence) / external: (named prior art) / reasoned: (written-out first-principles argument).
rationale — how the basis connects to the move's significance.
downsides — tradeoffs or costs.
confidence — 0-100%.
complexity — Low / Medium / High.

Keep idea cards expanded; add a jump-list when the section is long. Unlike plan Implementation Units, ideation idea cards are meant to be read in full to choose a direction — do not hide their substance behind default-closed <details>. But the Ranked Ideas section is typically 5-7 cards and runs long in HTML, so add a within-section jump-list of the ranked titles (anchor links to each card) at the top of the section, per the rendering reference's within-section sub-nav affordance.

Illustrative visuals — decide on the idea's shape, not on how clear the prose reads. A well-placed visual can make a direction land faster for a human scanning a set of candidates. Decide per survivor — none, a few, or most may warrant one; there is no quota and no cap.

Watch one trap when you make this call: the prose always conveys the idea (that is the hard rule below), and as a text-native reasoner you will tend to read your own prose, judge it "clear," and conclude no visual is needed — which quietly under-produces the visuals that actually help a reader. So "the prose is already clear" is never the reason to skip. The real question is what the idea hinges on, and whether that has a shape a picture carries faster than a sentence.

Concrete-vs-abstract is the wrong axis. Don't reach for a visual because an idea feels big or conceptual, and don't skip one because it feels small or concrete. A new-feature concept is often the best candidate — the reader has to picture an unfamiliar arrangement — while many concrete changes (an error fix, a drop-in dependency swap) have nothing structural to draw. Ask what the idea hinges on, not how abstract it is.

Hinges on a structure → lean toward a visual. A relationship between parts, a flow or sequence, a before/after contrast, a structural arrangement, an analogy mapping (especially cross-domain ideas), a quantitative comparison. A picture lands these faster than a sentence even when the prose is perfectly clear — and it should show the basis or the why-it-matters, not restate the title. New-feature concepts frequently live here.
A single point with nothing structural to show → no visual. A renamed thing, a copy change, "handle the null case," a drop-in library swap — there is no shape a diagram would add; one here is decoration. Size and abstraction don't decide this: a sweeping concept can still be one proposition ("ship dark mode"), and a small concrete fix can still re-route how two parts talk (real shape, worth drawing).

Decoration — a visual with no shape to show, or one that just restates the title — is the failure mode, and it is slop whether it appears once or five times. A visual that genuinely shows the idea's shape is never slop, however many ideas warrant one.

Two constraints on any visual you do add:

Stay at the idea's altitude — illustrative, not a spec. This is the opposite of a plan or requirements diagram. The shared rendering reference treats plan diagrams as authoritative content and forbids "directional sketch" framing; ideation visuals are the reverse — deliberately directional overviews of a direction nobody has committed to yet. Keep them conceptual (contrast, analogy, rough flow). Detailed architecture, sequence diagrams, and wireframes belong downstream in ce-brainstorm / ce-plan once a direction is chosen, not here.
Keep the prose standing alone. A reader who ignores the visual still gets the complete idea and its basis. The visual accelerates understanding; it never carries content found nowhere else.

Rendering mechanics (inline SVG in HTML with the layout-legibility and halo rules; a fenced mermaid block in markdown when the shape suits it) follow the rendering reference's Diagrams section — but that section's plan-centric, authoritative-diagram framing is overridden here by the illustrative, decide-per-idea stance above.

Rejection Summary

A table of considered-and-cut ideas with a one-line reason each. When an axis ended with zero survivors despite recovery, record it as its own row so the coverage gap is visible rather than silently absent.

Markdown skeleton

The section shape both formats carry. In markdown it is written literally (omit clearly irrelevant fields only when necessary); in HTML the same sections render per html-rendering.md.

---
date: YYYY-MM-DD
topic: <kebab-case-topic>
focus: <optional focus hint>
mode: <repo-grounded | elsewhere-software | elsewhere-non-software>
---

# Ideation: <Title>

## Grounding Context
[Grounding summary from Phase 1 — "Codebase Context" in repo mode, "Topic Context" in elsewhere mode]

## Topic Axes
[3-5 axes from Phase 1.5, one per line, OR a single `Decomposition skipped — ...` line. Omit the section if not applicable.]

## Ranked Ideas

### 1. <Idea Title>
**Description:** [Concrete explanation]
**Axis:** [Topic axis this idea targets — omit when decomposition was skipped]
**Basis:** [`direct:` / `external:` / `reasoned:` — quoted, cited, or written-out argument]
**Rationale:** [How the basis connects to the move's significance]
**Downsides:** [Tradeoffs or costs]
**Confidence:** [0-100%]
**Complexity:** [Low / Medium / High]

## Rejection Summary

| # | Idea | Reason Rejected |
|---|------|-----------------|
| 1 | <Idea> | <Reason rejected> |

[When applicable, append axis-coverage gaps as their own rows so the gap is visible:]
| - | axis: <name> | recovery skipped (cap reached) — no survivors on this axis |

No process exhaust

Keep engineering-process metadata out of the artifact — no "captured at Phase X" notes, no skill-pointer "next steps", no italic provenance lines. The reader wants the ideas and their basis. (HTML carries a single visible composition-signal footer per the html-rendering invariant; that is the one provenance element that belongs in the doc.)

8.5 KiB Raw Permalink Blame History