Skip to content

The regeneration prompt

Every page carries a collapsible block containing the brief for rebuilding itself. This is the difference between a page someone maintains and a page someone replaces.

Why it goes in the page

The page outlives the conversation that produced it, and gets forwarded to people with no access to that conversation. Six months on, the person asked to "update the roadmap" has the HTML file and nothing else. If the method lives only in a chat log, they start from scratch and the page's conventions die with the original author.

Putting it in the page also makes staleness visible: a block describing a hand-edited file, on a page that is now built by a script, is obviously wrong to anyone who opens it.

Two forms — pick by who will rebuild it

Short brief (default). The rebuilder has this library, this skill, and the cited repos. The block does not restate the method; it names the skill, links the library, lists the sources, gives the build and verify commands, and adds only what is specific to this page. Roughly 50 lines.

Self-contained prompt (exception). The rebuilder may have none of that — a page handed to a vendor, another business unit, or anyone outside the library's reach. The block has to carry the design system rules, diagram conventions and build steps inline, because nothing else will. Roughly 180 lines.

Default to the short brief. Duplicating the skill into every page means every page's copy goes stale independently, and they will disagree with each other before they disagree with the skill. Reach for the long form only when you can name the reader who will not have the library.

Short brief — structure

  1. ROLE — one paragraph: what this page is.
  2. METHOD — name the skill, say it is not to be improvised, and link the library's Azure DevOps remote plus the skill path. Say explicitly that nothing on the page overrides the skill.
  3. SOURCES — every source document by path, with the repo named, and the instruction to read each in full first. Add: paths move; if a file is not where it was, search the docs tree and follow related_docs frontmatter.
  4. THIS PAGE — source path, build command, verify command. State plainly: edit the source, never the built file.
  5. WHAT IS SPECIFIC TO THIS PAGE — the two or three judgement calls the skill cannot know. Which source wins when two disagree. Which figures are provisional. A named person who is structural to the plan. Nothing that is already in the skill.
  6. BEFORE PUBLISHING — update the "Updated ⟨date⟩" line, and update this block if the method changed in the same edit.

Close with a "Last generated" line: the date, and what changed.

Rules for the prompt itself

  • Plain text inside <pre><code>. It gets copied into another tool. No markdown syntax, no smart quotes, no em dashes — hyphens survive round trips.
  • Remember it is HTML. <date> must be written &lt;date&gt; in the source file. This is easy to miss and produces an invisible tag.
  • Name commands, not descriptions. make build-reports beats "run the build".
  • Link the library, do not just name it. A reader who has never seen it needs the remote: https://github.com/wiresuncrossed/hoen-library Put it in the prose above the prompt as a real link as well as inside the prompt text, so it is clickable.
  • Update it in the same edit as the thing it describes. The prompt's own final step says so; honour it.

Also give the reader the swatches

Above the prompt, show the resolved light-mode palette as swatches with both the role name and the DS token it aliases (--accent --rpt-blue). Someone checking brand compliance can then do it by eye, without reading CSS — and it stays useful whichever form of prompt the page carries.