plannotator-visual-explainer

Name: plannotator-visual-explainer
Author: backnotprop

7.2kstars517forks

How to install plannotator-visual-explainer?

backnotprop/plannotator/plannotator-visual-explainer

$npx -y skills add backnotprop/plannotator --skill plannotator-visual-explainer

Installs into the current project.

Summary

Generate self-contained HTML visualizations with Plannotator theming. Use for implementation plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive approach

Files · 1

View on GitHub

SKILL.md

1	# Plannotator Visual Explainer
2
3	Three paths depending on content type. Each has its own references and structure.
4
5	## Route by content type
6
7	Implementation plan, design doc, or proposal → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.
8
9	PR explainer, diff review, or code change walkthrough → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.
10
11	Everything else (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
12
13	## Delivery
14
15	Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
16
17	For any deliverable that uses Mermaid, render every diagram with Mermaid 11 in both the light
18	and dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,
19	empty SVG, or error output such as `aria-roledescription="error"` or `Syntax error in text`
20	means the explainer is not deliverable. Fix the diagram or theme configuration and rerun both
21	palettes until every SVG passes.
22
23	Plans/proposals (user should approve/deny):
24	```bash
25	plannotator annotate <file> --gate
26	```
27
28	Everything else (informational):
29	```bash
30	plannotator annotate <file>
31	```
32
33	---
34
35	## Plan path
36
37	For implementation plans, design docs, feature specs, migration guides, and proposals.
38
39	Before generating, read:
40	1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
41	2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow
42
43	Document structure (in order, pick what fits):
44
45	1. Header — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)
46	2. Summary strip — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)
47	3. Milestones / timeline — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.
48	4. Architecture / data flow — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.
49	5. Mockups — build UI mockups in HTML/CSS directly, not as descriptions
50	6. Key code — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.
51	7. Risks & mitigations — table with severity badges (HIGH/MED/LOW)
52	8. Open questions — callout cards with decision owner ("Decide with: backend team")
53
54	Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
55
56	Adapt to the task: Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
57
58	Quality bar: The plan answers "what, why, and how" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.
59
60	---
61
62	## PR path
63
64	For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
65
66	Before generating, read:
67	1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
68	2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels
69
70	Document structure (in order, pick what fits):
71
72	1. Header — PR title, meta strip (file count, +/- lines, branch, author)
73	2. TL;DR — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.
74	3. Why — motivation and before/after comparison (two-column grid)
75	4. File tour — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a "why" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.
76	5. Risk map — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).
77	6. Where to focus — numbered callout cards. Each names a file/function and describes the concern.
78	7. Test plan — checkbox-style verification checklist
79	8. Rollout (if applicable) — phased deployment with feature flags
80
81	Use Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.
82
83	---
84
85	#

People who liked this also viewed

6 picks

Type

plannotator-visual-explainer

7.2kstars517forks

View on GitHub

How to install plannotator-visual-explainer?

backnotprop/plannotator/plannotator-visual-explainer

$npx -y skills add backnotprop/plannotator --skill plannotator-visual-explainer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Plannotator Visual Explainer
2
3	Three paths depending on content type. Each has its own references and structure.
4
5	## Route by content type
6
7	Implementation plan, design doc, or proposal → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.
8
9	PR explainer, diff review, or code change walkthrough → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.
10
11	Everything else (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
12
13	## Delivery
14
15	Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
16
17	For any deliverable that uses Mermaid, render every diagram with Mermaid 11 in both the light
18	and dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,
19	empty SVG, or error output such as `aria-roledescription="error"` or `Syntax error in text`
20	means the explainer is not deliverable. Fix the diagram or theme configuration and rerun both
21	palettes until every SVG passes.
22
23	Plans/proposals (user should approve/deny):
24	```bash
25	plannotator annotate <file> --gate
26	```
27
28	Everything else (informational):
29	```bash
30	plannotator annotate <file>
31	```
32
33	---
34
35	## Plan path
36
37	For implementation plans, design docs, feature specs, migration guides, and proposals.
38
39	Before generating, read:
40	1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
41	2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow
42
43	Document structure (in order, pick what fits):
44
45	1. Header — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)
46	2. Summary strip — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)
47	3. Milestones / timeline — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.
48	4. Architecture / data flow — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.
49	5. Mockups — build UI mockups in HTML/CSS directly, not as descriptions
50	6. Key code — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.
51	7. Risks & mitigations — table with severity badges (HIGH/MED/LOW)
52	8. Open questions — callout cards with decision owner ("Decide with: backend team")
53
54	Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
55
56	Adapt to the task: Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
57
58	Quality bar: The plan answers "what, why, and how" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.
59
60	---
61
62	## PR path
63
64	For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
65
66	Before generating, read:
67	1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
68	2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels
69
70	Document structure (in order, pick what fits):
71
72	1. Header — PR title, meta strip (file count, +/- lines, branch, author)
73	2. TL;DR — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.
74	3. Why — motivation and before/after comparison (two-column grid)
75	4. File tour — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a "why" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.
76	5. Risk map — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).
77	6. Where to focus — numbered callout cards. Each names a file/function and describes the concern.
78	7. Test plan — checkbox-style verification checklist
79	8. Rollout (if applicable) — phased deployment with feature flags
80
81	Use Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.
82
83	---
84
85	#

People who liked this also viewed

6 picks

Type