john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ce-brainstorm): add conditional visual aids to requirements documents (#437)

Browse Source 
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Trevin Chow
2026-03-29 11:13:19 -07:00
committed by GitHub
parent d2b24e07f6
commit bd02ca7df0
2 changed files with 196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
plugins/compound-engineering/skills/ce-brainstorm/SKILL.md
View File

@@ -220,6 +220,34 @@ topic: <kebab-case-topic>
[If `Resolve Before Planning` is not empty: `→ Resume /ce:brainstorm` to resolve blocking questions before planning]
```
**Visual communication** — Include a visual aid when the requirements would be significantly easier to understand with one. Visual aids are conditional on content patterns, not on depth classification — a Lightweight brainstorm about a complex workflow may warrant a diagram; a Deep brainstorm about a straightforward feature may not.
**When to include:**
| Requirements describe... | Visual aid | Placement |
|---|---|---|
| A multi-step user workflow or process | Mermaid flow diagram or ASCII flow with annotations | After Problem Frame, or under its own `## User Flow` heading for substantial flows (>10 nodes) |
| 3+ behavioral modes, variants, or states | Markdown comparison table | Within the Requirements section |
| 3+ interacting participants (user roles, system components, external services) | Mermaid or ASCII relationship diagram | After Problem Frame, or under its own `## Architecture` heading |
| Multiple competing approaches being compared | Comparison table | Within Phase 2 approach exploration |
**When to skip:**
- Prose already communicates the concept clearly
- The diagram would just restate the requirements in visual form without adding comprehension value
- The visual describes implementation architecture, data schemas, state machines, or code structure (that belongs in `ce:plan`)
- The brainstorm is simple and linear with no multi-step flows, mode comparisons, or multi-participant interactions
**Format selection:**
- **Mermaid** (default) for simple flows — 5-15 nodes, no in-box annotations, standard flowchart shapes. Use `TB` (top-to-bottom) direction so diagrams stay narrow in both rendered and source form. Source should be readable as fallback in diff views and terminals.
- **ASCII/box-drawing diagrams** for annotated flows that need rich in-box content — CLI commands at each step, decision logic branches, file path layouts, multi-column spatial arrangements. More expressive than mermaid when the diagram's value comes from annotations within steps. Follow 80-column max for code blocks, use vertical stacking.
- **Markdown tables** for mode/variant comparisons and approach comparisons.
- Keep diagrams proportionate to the content. A simple 5-step workflow gets 5-10 nodes. A complex workflow with decision branches and annotations at each step may need 15-20 nodes — that is fine if every node earns its place.
- Place inline at the point of relevance, not in a separate section.
- Conceptual level only — user flows, information flows, mode comparisons, component responsibilities. Not implementation architecture, data schemas, or code structure.
- Prose is authoritative: when a visual aid and surrounding prose disagree, the prose governs.
After generating a visual aid, verify it accurately represents the prose requirements — correct sequence, no missing branches, no merged steps. Diagrams without code to validate against carry higher inaccuracy risk than code-backed diagrams.
For **Standard** and **Deep** brainstorms, a requirements document is usually warranted.
For **Lightweight** brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
@@ -236,6 +264,7 @@ Before finalizing, check:
- Are any unresolved items actually product decisions rather than planning questions?
- Did implementation details leak in when they shouldn't have?
- Is there a low-cost change that would make this materially more useful?
- Would a visual aid (flow diagram, comparison table, relationship diagram) help a reader grasp the requirements faster than prose alone?
If planning would need to invent product behavior, scope boundaries, or success criteria, the brainstorm is not complete yet.