explorable_plan_pages v1.0.0

name: "explorable_plan_pages" description: "Turn a long written plan in plain Markdown into one explorable review page a reviewer can decide from: decisions and open questions first, the mechanism as a diagram, steps stepped through one at a time with a safe stopping point on each, costs and risks in one place with their tables, and a decision form that composes the reply back into the plan file, with each revision built as a new version instead of an overwrite. Ships a tested builder plus contrast and phone-width checks. Use when a plan, proposal, RFC, or design doc is too long for a reviewer to act on, when a review needs a clear approve or block answer, or when plan revisions keep overwriting each other."

Purpose

A long plan usually fails at review, not at writing. The reviewer has to hunt for what they are being asked to decide, the steps blur together, and the costs sit in a paragraph on page four. This skill turns any existing plan document in plain Markdown into a single self contained HTML page built for one job: a decision.

The page works from the plan you already have. There is no special plan file format to adopt, no git history to keep, and no theme step. You point the builder at a Markdown file and get a page. Revisions are new version files, so what a reviewer saw last time stays on disk unchanged.

Bundled tools, both tested in this skill:

• scripts/build_page.py builds the page and refuses to overwrite an existing version.
• scripts/check_page.py checks the palette against WCAG 2.2 AA contrast, checks phone width behaviour, and checks that the sections are in decision order.
• examples/sample-plan.md and examples/sample-plan-v2.md carry one worked plan through two versions, including a review reply pasted back in and a decision changed by the cost table.

Workflow

1. Read the plan for decidability first

• List what the reviewer must decide. If you cannot name the decisions, the plan is not ready for a page. Send it back with that note instead of building a prettier version of an undecidable document.
• Check each decision for options and a recommendation. A decision card with no recommendation forces the reviewer to do the author's work.
• Check the open questions. Mark which ones block which decision. A blocking question with no owner needs an owner before review.
• Check every step for a stopping point. Write missing ones with the author, in the plan file, before building. The format and the test for a good one are in references/page-anatomy.md.
• Check costs and risks. Numbers belong in tables with a unit and a basis. Risks belong in a table with impact and mitigation. Move stray numbers out of prose and into the tables.

2. Shape the plan file, lightly

• Keep the author's file and voice. Add or rename level 2 headings only where the builder needs them: Decisions, Open Questions, How It Works, Steps, Costs, Risks. The keyword matching table is in references/markdown-conventions.md.
• Add a Mermaid flowchart block under How It Works if the plan has none. Keep it to about eight nodes, use flowchart TD or flowchart LR, nodes as A[Text], a decision as C{Text}, edges as A --> B. Never use the word "end" in lowercase as node text, it breaks Mermaid flowcharts.
• Do not renumber or reformat the rest of the plan. The Full plan section on the page renders it as written, so heavy editing only creates a diff the author did not agree to.

3. Build the page

• Run the builder from the skill folder:

python3 scripts/build_page.py path/to/plan.md --out-dir path/to/review-pages

• Read back what it prints. It reports the version it created and the counts of decisions, questions, and steps it found. A count of zero for decisions or steps means the headings did not match. Fix the plan headings and build again, as a new version.
• The output is one HTML file with inline CSS and JavaScript. It needs no network, no build step after this one, and no server. Send the file itself or host it anywhere static files work.

4. Run the checks, every time

• Run the checker on the file you just built:

python3 scripts/check_page.py path/to/review-pages/plan-v1.html

• Contrast checks use the WCAG 2.2 AA thresholds: 4.5 to 1 for normal text, 3 to 1 for large text and for user interface parts such as borders. Ratios use the WCAG relative luminance formula with no rounding up, so 4.499 to 1 fails. The shipped palette passes at 17.40 to 1 for body text and 7.84 to 1 for the accent on white.
• Phone width checks cover the parts of WCAG 2.2 reflow that a static check can prove: a viewport meta tag, a narrow width media query, tables inside a scrolling wrapper so the page itself does not scroll sideways at 320 CSS pixels, no fixed width over 320 pixels, and buttons at least 24 CSS pixels tall. The builder uses 44 pixels.
• Order checks confirm decisions come before the mechanism, the mechanism before the steps, and the decision form last. If a check fails, fix the builder input or the plan and rebuild as a new version. Never hand edit the generated HTML to make a check pass, the next build would lose the fix.

5. Walk the page like the reviewer

• Read only the Decisions and Open questions sections. Can you decide from those two alone, for the non blocking decisions? If not, the cards are too thin. Flesh them out in the plan and rebuild.
• Step through the steps with Next. At each step, read the stopping point box out loud. If it does not tell you what state the work is in, it fails, however tidy it looks.
• Look at Costs and risks on a phone width window or a narrow browser. Tables may scroll inside their wrapper. The rest of the page may not scroll sideways, and no text may be cut off.
• Fill in the decision form once, as a test. Compose the reply, read the Markdown it produces, and confirm a plan author could paste it into the plan file and act on it without asking you what you meant.

6. Issue revisions as new versions

• When the reviewer replies, paste the composed reply into the plan file under a ## Review Replies heading. That is where the sample v2 plan keeps it.
• Edit the plan, add a one line changelog at the top saying what changed and why, and remove answered questions from Open Questions.
• Build again with the same command. The builder sees the existing version files and writes the next number. It refuses an explicit version that already exists, and there is no force flag.
• Send the reviewer the new version file and name the version in your message, so nobody reviews a stale copy by mistake.

Output Contract

Deliver, for each review round:

1. One HTML file named <plan-stem>-v<N>.html, self contained, that passes scripts/check_page.py with zero failures.
2. The builder line for that file: version, decision count, question count, step count.
3. The checker output, or a plain statement that it passed with the contrast ratios it reported.
4. A short note naming what is missing from the plan itself, if anything: decisions with no recommendation, steps with no stopping point, numbers with no basis. These are plan defects, reported as such, not hidden by the page.
5. For a revision, the changelog line from the plan and the previous version filename, so the reviewer can compare.

Operating Rules

1. Every factual claim in the page comes from the plan file. The builder adds structure, not facts. If the plan states a cost, the page shows that cost with the plan's own notes. Never invent a number, a date, or a basis to fill a table.
2. Accessibility numbers in this skill are WCAG 2.2: contrast 4.5 to 1 for normal text and 3 to 1 for large text under Success Criterion 1.4.3, 3 to 1 for interface parts under 1.4.11, reflow at 320 CSS pixels under 1.4.10, and a 24 by 24 CSS pixel minimum target size under 2.5.8. If you change the palette, rerun the checker and quote its measured ratios, not the old ones.
3. Line length on the page is a design choice, set by the builder's container and type size. Guidance in the typography sources puts comfortable reading at roughly 45 to 75 characters per line. Do not present that range as a WCAG rule, it is not one.
4. Never overwrite a built version. If a build is wrong, build the next version and say what changed. Deleting old versions to tidy a folder destroys the review history this skill exists to keep.
5. Never hand edit generated HTML. Fix the plan or the builder, then rebuild. A hand edit passes once and fails every round after.
6. A page with zero decisions is a failed build, even if the checker passes. Report it as a plan that is not ready for review, with the missing pieces named.
7. Keep the reply loop inside the plan file. Replies that live only in chat or email get lost, and the next version then answers questions nobody can find. The composed Markdown reply, pasted into the plan, is the record.
8. No git, no theme, and no external diagram service are required at any step. If a team wants the pages in git or under their own styling later, that is their choice on top of this workflow, not a prerequisite for a reviewer to decide today.