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

feat(git-commit-push-pr): add conditional visual aids to PR descriptions (#444)

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

131
docs/plans/2026-03-29-003-feat-pr-description-visual-aids-plan.md Normal file
View File

@@ -0,0 +1,131 @@
---
title: "feat(git-commit-push-pr): Add conditional visual aids to PR descriptions"
type: feat
status: completed
date: 2026-03-29
---
# feat(git-commit-push-pr): Add conditional visual aids to PR descriptions
## Overview
Add visual communication guidance to git-commit-push-pr's Step 6 so PR descriptions can include mermaid diagrams, ASCII art, or comparison tables when the change is complex enough to warrant them. Follows the same content-pattern-based conditional approach already used in ce:brainstorm (#437) and ce:plan (#440), adapted for the PR description surface where reviewers scan quickly rather than study deeply.
## Problem Frame
Complex PRs with architectural changes, user flow modifications, or multi-component interactions currently get text-only descriptions. Even when the PR was built from a plan that contains visual aids, those visuals don't carry through to the PR description. Reviewers must reconstruct the mental model from prose alone.
PR #442 demonstrates this: a cross-target change with a 6-row decision matrix (which it did include as a markdown table) and multi-component interaction patterns. But for PRs involving workflow changes, data flow modifications, or component architecture shifts, the description has no guidance to include flow diagrams or interaction diagrams that would dramatically improve reviewer comprehension.
The gap: ce:brainstorm and ce:plan both now produce visual aids when content warrants it, but the downstream PR description -- the artifact reviewers actually see first -- has no equivalent guidance.
## Requirements Trace
- R1. The skill includes guidance for when visual aids genuinely improve a PR description
- R2. Visual aids are conditional on content patterns (what the PR changes), not on PR size alone -- a small PR that changes a complex workflow may warrant a diagram; a large mechanical refactor may not
- R3. The trigger bar is higher than ce:brainstorm or ce:plan -- PR descriptions are scanned by reviewers, not studied deeply
- R4. Three visual aid types: mermaid flow/interaction diagrams, ASCII annotated flows, and markdown tables (tables already partially covered by the existing "Markdown tables for data" writing principle)
- R5. Within generated PR descriptions, visual aids are placed inline at the point of relevance, not in a separate section
- R6. The existing Step 6 structure, sizing table, writing principles, and state machine flow of the skill remain intact
## Scope Boundaries
- Not adding visual aids to every PR -- the guidance is conditional with explicit skip criteria
- Not changing the sizing table or other Step 6 subsections
- Not touching Steps 1-5 or Steps 7-8 (the state machine structure must be preserved per institutional learnings)
- Not adding plan/brainstorm document extraction -- this is about the PR diff, not upstream artifacts
## Context & Research
### Relevant Code and Patterns
- `plugins/compound-engineering/skills/git-commit-push-pr/SKILL.md` -- the skill to modify; Step 6 spans lines 187-333 with subsections: Detect base branch, Gather branch scope, Sizing the change, Writing principles, Numbering and references, Compound Engineering badge
- `plugins/compound-engineering/skills/ce-brainstorm/SKILL.md` (lines 223-249) -- visual communication pattern: "When to include / When to skip" table, format selection, prose-is-authoritative rule
- `plugins/compound-engineering/skills/ce-plan/SKILL.md` (lines 581-612) -- plan-readability visual aids following the same structural pattern, with disambiguation from Section 3.4
- Existing "Markdown tables for data" writing principle (line 280) -- already covers one visual medium (tables for before/after and trade-off data); the new guidance extends to mermaid and ASCII
### Institutional Learnings
- The git-commit-push-pr skill is structured as a state machine with explicit transition checks. Changes must be strictly additive to the PR body composition phase -- do not alter or reorder git state checks (see `docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md`)
- GitHub renders mermaid code blocks natively in PR descriptions (supported since 2022)
- No existing learnings about mermaid gotchas or diagram generation failures in docs/solutions/
- Prose-is-authoritative is an established invariant across brainstorm and document-review skills
## Key Technical Decisions
- **Insertion point: new `#### Visual communication` subsection after Writing principles (after line 290), before Numbering and references (line 292)**: This extends the writing guidance rather than the sizing logic. The sizing table determines description *depth*; visual aids are about *medium*. Placing here preserves the flow: size the description -> write it following principles -> add visual aids when warranted -> handle numbering -> add badge.
- **Higher trigger bar than sibling skills**: PR descriptions are a scanning surface, not a studying surface. ce:brainstorm triggers on "multi-step user workflow" and ce:plan triggers on "4+ units with non-linear dependencies." PR triggers should reflect what makes a *reviewer's job harder without a visual* -- architectural changes touching 3+ interacting components, workflow/pipeline changes with non-obvious flow, state or mode changes. The "When to skip" list should explicitly reinforce that small/simple changes (already handled by the sizing table) never get diagrams.
- **Extend beyond the existing "Markdown tables for data" principle**: The existing bullet at line 280 covers tables for performance data and trade-offs. The new Visual communication subsection incorporates table format guidance within its own format selection list (consistent with sibling skills' self-contained pattern) and extends coverage to mermaid flow diagrams and ASCII interaction diagrams. The existing bullet stays as-is.
- **Self-contained format selection, consistent with sibling skills**: Skills can't reference each other's guidance. Restate the format framework (mermaid default with TB direction, ASCII for annotated flows, markdown tables for comparisons) with PR-appropriate calibration. Keep diagrams smaller than plan/brainstorm -- 5-10 nodes typical for a PR description, up to 15 only for genuinely complex changes.
## Open Questions
### Resolved During Planning
- **Should the description update workflow (DU-3) also get visual aid guidance?** Yes. DU-3 says "write a new description following the writing principles in Step 6." Since visual communication guidance is part of Step 6's writing guidance, DU-3 inherits it automatically through the existing reference. No separate addition needed.
- **Should we extract plan/brainstorm visuals into PR descriptions?** No. The PR description should be derived from the branch diff, not from upstream artifacts. If the diff shows a workflow change, the PR description should diagram the workflow based on what the diff reveals.
### Deferred to Implementation
- Mermaid node count thresholds start at 5-10 typical, up to 15 for genuinely complex changes (per Key Technical Decisions). These are starting values -- monitor initial output and adjust if diagrams are too sparse or too dense
## Implementation Units
- [x] **Unit 1: Add visual communication subsection to Step 6**
**Goal:** Add a `#### Visual communication` subsection to Step 6 with conditional inclusion guidance following the established "When to include / When to skip" pattern.
**Requirements:** R1, R2, R3, R4, R5, R6
**Dependencies:** None
**Files:**
- Modify: `plugins/compound-engineering/skills/git-commit-push-pr/SKILL.md`
**Approach:**
- Insert the new subsection after the Writing principles section (after line 290) and before Numbering and references (line 292)
- Use the same structural template as ce:brainstorm and ce:plan: opening conditional principle, "When to include" table, "When to skip" list, format selection guidance, prose-is-authoritative rule, verification instruction
- Adapt triggers for PR-specific content patterns: architectural changes with 3+ components, workflow/pipeline changes, state/mode introduction, data model changes with entity relationships
- Calibrate to PR scanning context: higher bar for inclusion, smaller diagrams (5-10 nodes typical), explicit skip for small/simple changes
- Reference the existing "Markdown tables for data" writing principle for table guidance rather than duplicating it
**Patterns to follow:**
- `plugins/compound-engineering/skills/ce-brainstorm/SKILL.md` lines 223-249 (visual communication section structure)
- `plugins/compound-engineering/skills/ce-plan/SKILL.md` lines 581-612 (plan-readability visual aids)
**Test scenarios:**
- Happy path: The new subsection is syntactically valid markdown with correct heading level (`####`) matching sibling subsections in Step 6
- Happy path: The "When to include" table has PR-appropriate triggers (not copy-pasted from brainstorm/plan)
- Happy path: The "When to skip" list explicitly covers small/simple changes to reinforce the sizing table
- Edge case: The existing "Markdown tables for data" writing principle at line 280 remains unchanged
- Integration: DU-3 inherits the new guidance through its existing "following the writing principles in Step 6" reference without any changes to the DU-3 section
**Verification:**
- The SKILL.md file has a new `#### Visual communication` subsection between Writing principles and Numbering and references
- The subsection follows the same structural pattern as ce:brainstorm lines 223-249 (conditional principle, When to include table, When to skip list, format selection, verification)
- The triggers are calibrated for PR descriptions (higher bar than plan/brainstorm)
- No changes outside of Step 6's description writing guidance area
- `bun test` passes (if any frontmatter or structure tests exist for this skill)
## System-Wide Impact
- **Interaction graph:** The description update workflow (DU-3) references Step 6's writing principles and inherits the new guidance automatically. No other skills reference git-commit-push-pr's internal guidance.
- **Unchanged invariants:** Steps 1-5 (git state machine), Step 7 (PR creation/update), Step 8 (reporting) are not touched. The sizing table, numbering/references, and badge sections within Step 6 are not modified.
## Risks & Dependencies
| Risk | Mitigation |
|------|------------|
| Visual aids trigger too often, bloating simple PR descriptions | Higher trigger bar than sibling skills + explicit skip for small/simple changes + "Brevity matters" principle already in Step 6 |
| Mermaid diagrams don't render in all PR viewing contexts (email, Slack previews) | Mermaid source is readable as text fallback; TB direction keeps source narrow |
| Diagram accuracy -- no code to validate against | Verification instruction (same as sibling skills) to check diagram matches the diff |
## Sources & References
- Related PRs: #437 (brainstorm visual aids), #440 (plan visual aids)
- Related plans: `docs/plans/2026-03-29-001-feat-brainstorm-visual-aids-plan.md`, `docs/plans/2026-03-29-002-feat-plan-visual-aids-plan.md`
- Institutional learning: `docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md`
- GitHub mermaid support: confirmed natively in PR descriptions since 2022

222
docs/solutions/best-practices/conditional-visual-aids-in-generated-documents-2026-03-29.md Normal file
View File

@@ -0,0 +1,222 @@
---
title: Conditional visual aids in generated documents and PR descriptions
date: 2026-03-29
category: best-practices
module: compound-engineering plugin skills
problem_type: best_practice
component: documentation
symptoms:
- "Generated documents and PR descriptions lack visual aids that would improve comprehension of complex workflows and relationships"
- "No consistent criteria for when to include mermaid diagrams vs ASCII art vs markdown tables"
- "Dense prose obscures architectural relationships that a diagram would clarify instantly"
- "Downstream consumers recreate visuals from scratch because upstream documents did not include them"
root_cause: inadequate_documentation
resolution_type: documentation_update
severity: low
tags:
- visual-aids
- mermaid
- ascii-diagrams
- markdown-tables
- pr-descriptions
- skill-design
- document-generation
---
# Conditional visual aids in generated documents and PR descriptions
## Problem
AI-generated documents and PR descriptions default to prose-only output, even when the content -- multi-step workflows, behavioral mode comparisons, multi-participant interactions, dependency structures -- would be understood significantly faster with a visual aid. The gap is not "no diagrams." The gap is that there is no principled framework for deciding when a visual aid earns its place, which format to use, and how to calibrate for different output surfaces.
---
## Symptoms
- Readers mentally reconstruct workflows, dependency graphs, or mode differences from dense prose paragraphs
- Downstream consumers (ce:plan reading a brainstorm, reviewers reading a PR) create their own visual aids from scratch because the upstream document didn't include them
- Plans with 5+ implementation units and non-linear dependencies force readers to scan every unit's Dependencies field to reconstruct the execution graph
- System-Wide Impact sections naming multiple interacting surfaces read as a wall of prose when a component diagram would take seconds to scan
- PR descriptions for architecturally significant changes are text-only even though they were built from plans that contained visual aids
- Simple, linear documents include diagrams that add no comprehension value beyond restating the prose
---
## What Didn't Work
- **Always adding diagrams** -- treating visual aids as mandatory by depth classification, document length, or PR size produces noise. Reflexive diagram inclusion trains readers to skip them.
- **Never adding diagrams** -- prose-only output fails when content has branching flows, mode comparisons, or multi-participant interactions. Downstream consumers end up building the visuals themselves.
- **Wrong diagram type for the content** -- using a mermaid flow diagram when the value is in rich annotations within each step (CLI commands, decision logic) produces a diagram that strips out the useful detail.
- **Wrong abstraction level for the surface** -- code-level detail in a brainstorm diagram is premature. Product-level user flows in a plan's Technical Design section miss the point. Oversized diagrams in a PR description slow down reviewers.
- **Size/depth as the trigger** -- gating visual aids on "Standard" or "Deep" depth classification, or on PR line count, produces false positives (long but simple docs get unwanted diagrams) and false negatives (short but complex docs get none).
---
## Solution: The Conditional Visual Aid Pattern
Visual aids are conditional on **content patterns** -- what the content describes -- not on document size, depth classification, or surface type alone. Include a visual aid when the content would be significantly easier to understand with one; skip it when prose already communicates the concept clearly.
### 1. Content-Pattern Triggers (Not Size/Depth Triggers)
Whether to include a visual aid depends on WHAT the content describes, not HOW MUCH content there is. A Lightweight brainstorm about a complex workflow may warrant a diagram; a Deep brainstorm about a straightforward feature may not.
| Content describes... | Visual aid type | Notes |
|---|---|---|
| Multi-step workflow or process with branching | Flow diagram (mermaid or ASCII) | Shows sequence, branches, decision points |
| 3+ behavioral modes, variants, or states | Comparison table (markdown) | Shows how modes differ across dimensions |
| 3+ interacting participants (roles, components, services) | Relationship/interaction diagram (mermaid or ASCII) | Shows who talks to whom and in what order |
| Multiple competing approaches or alternatives | Comparison table (markdown) | Structured side-by-side evaluation |
| 4+ units/stages with non-linear dependencies | Dependency graph (mermaid) | Shows parallelism, fan-in/fan-out, blocking order |
| Data pipeline or transformation chain | Data flow sketch (mermaid or ASCII) | Shows input/output transformations |
| State-heavy lifecycle | State diagram (mermaid) | Shows transitions and guards |
| Before/after performance or behavioral changes | Comparison table (markdown) | Structured quantitative comparison |
**Why content patterns beat size thresholds:** Size correlates weakly with structural complexity. A 200-line brainstorm about a simple CRUD feature is structurally simple. A 50-line brainstorm about a multi-actor authorization workflow is structurally complex. Pattern-based triggers correctly distinguish these; size-based triggers don't.
**Universal skip criteria:**
- Prose already communicates the concept clearly
- Diagram would just restate content in visual form without adding comprehension value
- Content is simple and linear with no multi-step flows, mode comparisons, or multi-participant interactions
- Visual describes detail at the wrong abstraction level for the surface
- Three or fewer items in a straight chain -- text is sufficient
- Diagram would be 3 nodes or fewer -- it adds ceremony without comprehension benefit
### 2. Which Visual Aid to Choose
```
+---------------------------+
| Does the content warrant |
| a visual aid at all? |
+-------------+-------------+
|
+--------+--------+
| |
No Yes
| |
Skip entirely What kind of content?
|
+--------------------+--------------------+
| | |
Flows/sequences Comparisons/data Relationships
| | |
+-----+-----+ Markdown table +-----+-----+
| | | |
Annotation Simple flow Simple graph Complex
density high? (5-15 nodes) (5-15 nodes) spatial
| | | layout
| Mermaid Mermaid |
ASCII ASCII
```
**Mermaid diagrams (default for most flow and relationship content)**
- Best for: simple flows (5-15 nodes), dependency graphs, sequence diagrams, state diagrams, component diagrams
- Strengths: renders as SVG in GitHub; source text readable as fallback in email, Slack, terminal, diff views; standardized syntax; easy to maintain
- Limitations: poor at rich in-box annotations; node labels must be concise; awkward for multi-line content within a node
- Use `TB` (top-to-bottom) direction for narrow rendering in both SVG and source fallback
**ASCII/box-drawing diagrams (when annotation density is high)**
- Best for: annotated flows with CLI commands, decision logic, file paths at each step; multi-column spatial arrangements; layouts where the value is in *annotations within steps*, not just the flow between them
- Strengths: renders identically everywhere (no renderer dependency); more expressive for in-box content
- Constraints: 80-column max for terminal and diff view compatibility; use vertical stacking to fit
- Choose over mermaid when: the diagram's value comes from what's written inside each box, not from the graph shape
**Markdown tables (structured comparison data)**
- Best for: mode/variant comparisons (3+ modes), before/after data, decision matrices, approach evaluations, trade-off summaries
- Strengths: wrap naturally in renderers; universally supported; dense information in scannable form
- Choose for any structured data that maps inputs to outputs or compares items across dimensions
### 3. Surface-Specific Calibration
Each output surface has different reading patterns. The trigger bar and diagram density must adjust.
| Surface | Reading pattern | Trigger bar | Abstraction level | Typical diagram size |
|---|---|---|---|---|
| Requirements (ce:brainstorm) | Studied deeply | Standard | Conceptual/product-level: user flows, information flows, mode comparisons | 5-20 nodes |
| Plan -- Technical Design (ce:plan 3.4) | Studied deeply | Work-characteristic-driven | Solution architecture: component interactions, data flow, state machines | 5-15 nodes |
| Plan -- Readability (ce:plan 4.4) | Studied deeply | Standard | Document structure: unit dependencies, impact surfaces, mode overviews | 5-15 nodes |
| PR description (git-commit-push-pr) | Scanned quickly | High | Change impact: what changed architecturally, what flows differently | 5-10 nodes |
Key distinctions:
- **Brainstorm**: conceptual level only. No implementation architecture, data schemas, or code structure.
- **Plan Technical Design vs. Plan Readability**: Section 3.4 diagrams describe *what's being built*. Section 4.4 diagrams help readers *comprehend the plan document itself*. These are complementary, not overlapping.
- **PR description**: highest bar. Only include when the change involves structural complexity a reviewer would struggle to reconstruct from prose alone. Derived from the branch diff, not from upstream plan/brainstorm artifacts.
### 4. Layout and Cross-Device Optimization
**TB direction for mermaid.** Top-to-bottom diagrams stay narrow in both rendered SVG and source text fallback. This matters for:
- GitHub's PR description view (limited horizontal space)
- Side-by-side diff views (source text appears as code block)
- Email/Slack notifications (source text is all that renders)
**80-column max for ASCII.** Terminal windows, diff views, and email clients clip or wrap beyond 80 columns. Use vertical stacking to fit complex content within column limits.
**Proportionality: 5-15 nodes typical.** Every node should earn its place:
- Simple 5-step workflow -> 5-10 nodes
- Complex workflow with decision branches -> 15-20 nodes if every node earns its place
- PR descriptions trend smaller (5-10 nodes); brainstorms and plans can trend larger
- Exceeding 15 should be because the content genuinely has that many meaningful steps
**Mermaid source as text fallback.** Many consumers first encounter generated documents through contexts that don't render mermaid:
- Email notifications of PR descriptions
- Slack link previews
- Terminal diff views and `git log` output
- RSS readers
Source text must be readable as text. TB direction and concise node labels help.
**Inline placement at point of relevance.** Always place visual aids where they help comprehension:
- Workflow diagram after Problem Frame, not in a "Diagrams" appendix
- Dependency graph before or after Implementation Units heading
- Comparison table within the section discussing modes or alternatives
- A separate "Diagrams" section invites diagrams for diagrams' sake
- Exception: substantial flows (>10 nodes) may warrant their own heading near the point of relevance
---
## Why This Works
The conditional, content-pattern-based approach ties the inclusion decision to an observable property of the content itself, not to a proxy metric. This produces correct decisions at both ends: a short brainstorm about a complex multi-actor workflow gets a diagram (trigger matches); a long brainstorm about a straightforward feature does not (no trigger matches).
Surface-specific calibration ensures the same core principle -- "include when content patterns warrant it" -- adapts to consumption context. The trigger bar rises and diagram sizes shrink as reading pattern shifts from deep study to quick scanning.
Self-contained format selection per skill (rather than cross-references) keeps skills independently functional while shared structural patterns (When to include / When to skip / Format selection / Prose-is-authoritative) maintain consistency.
The prose-is-authoritative invariant resolves the trust problem: when diagram and prose disagree, prose governs. No ambiguity for reviewers or implementers.
---
## Prevention
Concrete guidance for any skill that generates documents with visual aids:
1. **Use content-pattern triggers, not size/depth gates.** Define an explicit "When to include" table mapping content patterns to visual aid types. Never gate on depth classification or line count.
2. **Define explicit skip criteria.** Every "When to include" needs a "When to skip." Include at minimum: prose already clear, diagram would restate without value, content is simple/linear, visual is at wrong abstraction level.
3. **Make format selection self-contained per skill.** Each skill contains its own format guidance (mermaid, ASCII, markdown tables) with surface-appropriate calibration. Don't cross-reference other skills' guidance.
4. **Calibrate to the surface's reading pattern.** Define trigger bar relative to consumption context. Studied surfaces get standard bar; scanned surfaces get higher bar with smaller diagrams.
5. **Specify the abstraction level.** State what detail level belongs in visual aids for this surface. "Conceptual level only -- not implementation architecture" is the brainstorm example.
6. **Enforce prose-is-authoritative.** State that when visual aid and prose disagree, prose governs. Cross-skill invariant.
7. **Require post-generation accuracy check.** After generating any visual aid, verify it matches surrounding content -- correct sequence, no missing branches, no merged steps, no omitted participants.
8. **Use TB direction for mermaid, 80-column max for ASCII.** Layout constraints for cross-device compatibility.
9. **Place inline at point of relevance.** Never create a separate "Diagrams" section.
10. **Keep diagrams proportionate.** Every node earns its place. 5-15 nodes typical. Exceed 15 only for genuinely complex content.
---
## Related Issues
- `docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md` -- related but distinct: covers git-commit-push-pr state machine correctness, not output content quality
- GitHub issue #44 -- mermaid dark mode rendering, relevant when considering diagram styling
- PR #437 -- ce:brainstorm visual aids implementation
- PR #440 -- ce:plan visual aids implementation
- `docs/plans/2026-03-29-003-feat-pr-description-visual-aids-plan.md` -- git-commit-push-pr visual aids plan

33
plugins/compound-engineering/skills/git-commit-push-pr/SKILL.md
View File

@@ -289,6 +289,39 @@ Use this to select the right description depth:
- **No empty sections**: If a section (like "Breaking Changes" or "Migration Guide") doesn't apply, omit it entirely. Do not include it with "N/A" or "None".
- **Test plan -- only when it adds value**: Include a test plan section when the testing approach is non-obvious: edge cases the reviewer might not think of, verification steps for behavior that's hard to see in the diff, or scenarios that require specific setup. Omit it for straightforward changes where the tests are self-explanatory or where "run the tests" is the only useful guidance. A test plan for "verify the typo is fixed" is noise.
#### Visual communication
Include a visual aid when the PR changes something structurally complex enough that a reviewer would struggle to reconstruct the mental model from prose alone. Visual aids are conditional on content patterns -- what the PR changes -- not on PR size. A small PR that restructures a complex workflow may warrant a diagram; a large mechanical refactor may not.
The bar for including visual aids in PR descriptions is higher than in brainstorms or plans. Reviewers scan PR descriptions to orient before reading the diff -- visuals must earn their space quickly.
**When to include:**
| PR changes... | Visual aid | Placement |
|---|---|---|
| Architecture touching 3+ interacting components or services | Mermaid component or interaction diagram | Within the approach or changes section |
| A multi-step workflow, pipeline, or data flow with non-obvious sequencing | Mermaid flow diagram | After the summary or within the changes section |
| 3+ behavioral modes, states, or variants being introduced or changed | Markdown comparison table | Within the relevant section |
| Before/after performance data, behavioral differences, or option trade-offs | Markdown table (see the "Markdown tables for data" writing principle above) | Inline with the data being discussed |
| Data model changes with 3+ related entities or relationship changes | Mermaid ERD or relationship diagram | Within the changes section |
**When to skip:**
- The change is trivial -- if the sizing table routes to "1-2 sentences", skip visual aids
- Prose already communicates the change clearly
- The diagram would just restate the diff in visual form without adding comprehension value
- The change is mechanical (renames, dependency bumps, config changes, formatting)
- The PR description is already short enough that a diagram would be heavier than the prose around it
**Format selection:**
- **Mermaid** (default) for flow diagrams, interaction diagrams, and dependency graphs -- 5-10 nodes typical for a PR description, up to 15 only for genuinely complex changes. 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, email notifications, and Slack previews.
- **ASCII/box-drawing diagrams** for annotated flows that need rich in-box content -- decision logic branches, file path layouts, step-by-step transformations with annotations. 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, before/after data, and decision matrices.
- Keep diagrams proportionate to the change. A PR touching a 5-component interaction gets 5-8 nodes. A larger architectural change may need 10-15 nodes -- that is fine if every node earns its place.
- Place inline at the point of relevance within the description, not in a separate "Diagrams" section.
- Prose is authoritative: when a visual aid and surrounding description prose disagree, the prose governs.
After generating a visual aid, verify it accurately represents the change described in the PR -- correct components, no missing interactions, no merged steps. Diagrams derived from a diff (rather than from code analysis) carry higher inaccuracy risk.
#### Numbering and references
**Never prefix list items with `#`** in PR descriptions. GitHub interprets `#1`, `#2`, etc. as issue/PR references and auto-links them. Instead of: