/html-plan

name: html-plan
description: Write an implementation plan as one interactive HTML page - a tree of claims (why › what › how › where), each proved by one exhibit (UI mockup, state machine, call stack, schema or code), with the decisions the user has to make placed on the claim they change. Use when the user types /html-plan, or asks for a plan, RFC or design before building something that touches more than a couple of files.

html-plan

Plan this: $ARGUMENTS

You write **one HTML file by hand**. It holds a tree of claims. A small runtime draws the tree and lets the reader open it level by level, answer decisions, edit schemas, comment on anything, and copy one response back to you. Do not start building until that response arrives.

<this skill's directory>/
  runtime/htmlplan.css  htmlplan.js   ← link both from the page; pack inlines them
  runtime/pack.mjs                    ← lint + inline → one portable file (needs only node)
  references/blocks.md                ← every block, with syntax. Read it before you write.
  examples/scheduled-send.html        ← a full plan. Copy its shape.

The tree

Each level answers one question. The question picks the exhibit.

| Level | Answers | The claim is | Exhibit | |---|---|---|---| | `h1` | What is this? | a title: the change and the place, 3 to 7 words | none | | `details.thread` | Why? | — | the user's own words, as closed quotes | | 1 | What can someone now do or see? | a behaviour | `doc-mock`; `doc-machine` if it has a lifecycle | | 2 | How does that work? | one entrypoint, rule or record | `doc-calls`, `doc-schema`, or short `doc-code` | | 3 | Where? | `file:line` | `doc-code` |

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Scheduled Send Plan</title>                     <!-- a name: 2–4 words -->
<link rel="stylesheet" href="htmlplan.css">            <!-- pack finds the files by name; use the real path to runtime/ to preview unpacked -->
<script src="htmlplan.js" defer></script>
<body>
<header>
  <h1>Scheduling Sent Messages in PostBox</h1>                                 <!-- a title, not a sentence. No label line above it -->
  <doc-changes new="5" changed="4"></doc-changes>      <!-- files the plan will add, change or delete; drawn as "Proposed · 9 files +5 new ~4 changed" -->
  <details class="thread"><summary>Why · 2 requests</summary> …doc-quote… </details>      <!-- WHY: the user's own words -->
</header>
<main>
<doc-plan>
  <doc-claim>                                                     <!-- 1 · WHAT -->
    <p>The user can pick a time in the composer.</p>              <!-- first child: the claim -->
    <doc-mock frame="none" w="440">…</doc-mock>                   <!-- then ONE exhibit -->
    <doc-claim>                                                   <!-- 1.1 · HOW -->
      <p>“Send later” saves the message with a time. It does not send.</p>
      <doc-calls …>…</doc-calls>
      <doc-claim at="server/src/scheduled/routes.ts:18">          <!-- 1.1.1 · WHERE; at= matches a call row's @ path:line -->
        <p><b>routes.ts:18</b> · createScheduled()</p>
        <doc-code …>…</doc-code>
      </doc-claim>
    </doc-claim>
    <doc-claim>
      <p>A user can hold 50 scheduled messages at most.</p>
      <doc-code …>…</doc-code>
      <doc-ask id="limit">…</doc-ask>                             <!-- a decision sits on the claim it changes -->
    </doc-claim>
  </doc-claim>
  <doc-claim aux="shared"><p>Shared: one new table.</p><doc-schema lang="sql" …>…</doc-schema></doc-claim>
  <doc-claim aux="scope"><p>Not changing: normal send, drafts, the mail provider.</p><ul>…</ul></doc-claim>
</doc-plan>
</main>
</body></html>

Rules

`pack.mjs` checks 2, 3, 5, 6 (the count), 7 and 11. The rest are yours to check.

1. **Split the top level by behaviour.** Never by file, layer or order of work. Behaviour is the one split the reader can judge without reading code. 2. **Every claim at levels 1 and 2 is a sentence that can be true or false.** “A user can hold 50 scheduled messages at most.” Not “Message limit”. About 12 words at most. A level-3 claim is only a place: `file:line · symbol`. 3. **One exhibit per claim.** A second exhibit means a second claim. 4. **The closed tree is the summary.** Read only the level-1 claims aloud. They must tell the whole change. So write no TL;DR, no sections and no steps list. 5. **At most 5 children and 3 levels.** 6. **A decision sits on the claim it changes**, after the exhibit and before any child claims. Check the option you would pick. If an option removes a claim, say so: “claim 4 goes”. Ask only about forks that change what you build: 2 to 5 per plan. 7. **End with `aux="shared"`**, for a record or part several claims use (skip it if there is none), **and `aux="scope"`**, for what is not changing. 8. **Real over drawn.** Real paths and line numbers for code that exists; fill it with `src="path" lines="a-b"`. Mark code that does not exist yet as a sketch in its title. Quote the user's words; do not reword them. 9. **Schemas are text in the project's own language**: TypeScript, SQL, protobuf. Never a table or a made-up notation. 10. **A state machine shows the screen for each state** when the state changes what the user sees. Place its states on a grid. 11. **The page starts with a title.** The `h1` names the change and the place in 3 to 7 words: “Scheduling Sent Messages in PostBox”. It is not a sentence and not the goal. Put nothing above it: no “Plan · project” line. The level-1 claims tell what changes.

For a change with no visible behaviour, such as a refactor, make level 1 the guarantees: “Nothing a caller sees changes.”, “Each store has one owner.”

Words

The exhibits are the plan. Words only name them.

**Write all prose in ASD-STE100 Simplified Technical English (STE). Use no other style.** This rule applies to claims, captions, pins, questions, options and notes.

• **Approved words only.** Use a word only if the STE dictionary appro