| name | haipipe-board-page-for-skill |
| description | The VARIANT contract for a Board's numbered Skill and Agent mirror Pages. It loads haipipe-board-page for the base frame and adds only what a mirror Page needs: an Opening that introduces a unit instead of asking a rhetorical question, the derived-versus-authored split across three managed spans, state as a health judgment rather than a version, Aims as the unit's own open work, and Content as the unit's generated bytes. Use when writing or fixing a Skill or Agent Page, when its Opening reads like every other one, when a new unit ships and needs a Page, or when a retired unit's Page must be archived. Trigger: skill page, agent page, Skill-0, Agent-1, mirror page, skillpage, skill page Opening, working on a skill page, /haipipe-board-page-for-skill. |
| metadata | {"version":"0.4.2","last_updated":"2026-08-04","summary":"Now lives under page-types/ and composes its mirror-page structure with the current Page Phase."} |
/haipipe-board-page-for-skill · a skill page is not a decision page
LOAD haipipe-board-page FIRST. It owns the base: the sections and their fixed order, the five rows that define each one, the title rule, the numbering, and the evaluation contract.
This file adds only what a skill page needs and a decision page does not.
It never repeats a base rule, because a copied rule is the thing that goes a night out of date while the contract moves.
After resolving this Page Type, load the current contract from page-phases/; generated spans constrain the phase write surface but do not replace the phase authority test.
The two kinds this variant covers: both mirror something that ships elsewhere.
kind filename mirrors closes when
──────────────────────────────────────────────────────────────────────────
Skill Skill-<n>-<slug>.md one skill FOLDER · SKILL.md the unit ships
Agent Agent-<n>-<slug>.md one agent FILE · <name>.md the unit ships
NEITHER is ever counted in the board's settled total
<n> orders the roster and never carries the version, because a filename that changed every release would break every link to the page.
A skill is LOADED into a context and an agent is DISPATCHED into a fresh one (JL 260731), which is why they are two kinds and not one.
📄 The whole page, in one picture
Every rule in this file lands in one of these slots. Read this figure first; the sections below only say WHY.
# haipipe-board-page · v0.11.1 ← 🤖 title · the version is DERIVED
state: 🟡 in flux · door test passed ← 🧑 HEALTH + the evidence for it
owner: JL ← 🧑 who rules on this unit
method: three managed spans sync… ← 🧑 one line, how the page is kept
## Opening ← 🧑 YOURS. the three slots:
❶ what is it, what FOR ONE visible paragraph, then a
❷ when, vs ONE NAMED sibling BLANK LINE, then More details
❸ where it stands, with evidence as **Label**: prose parts
🚫 the lead sentence never ends in ?
## Writing Style ← 🧑 OPTIONAL, delete if unused
## Diagram
<!-- skill:tree:start … --> ← 🤖 the folder, one purpose line
**What `x` ships**: … ```tree``` per file · caption is generated
<!-- …:end --> an AGENT's tree is EMPTY: kept
**How `x` is used**: … ← 🧑 YOURS. caption, then ONE figure
```text WORKFLOW … ``` drawing how the unit is used
## Content
<!-- skill:body:start … --> ← 🤖 the unit's SKILL.md, its own
… the whole file … bytes. NEVER write in here.
<!-- …:end -->
## Aims ← 🧑 the UNIT's open work
- [ ] 🔧 <what it still owes> checkboxes, no A<n> ids
<why, indented>
## States ← 🧑 dated records, newest first
<one plain paragraph: where it stands>
- 260802 CC · 🔎 <title>
<what happened, indented>
## Files ← ❌ OMITTED. the tree above already
lists every file it ships
## Log
260802 2100 · <what changed by hand> ← 🧑 your lines go ON TOP
<!-- skill:log:start … --> ← 🤖 the unit's CHANGELOG, converted
<!-- …:end --> into dated Log lines
(the markers above are shortened on purpose: a literal one inside this figure reaches every mirror page's Content span, and on 260803 that fed sync a fake marker and cost one page its Aims, States and Log.)
🤖 = skillpage.py writes it and sync rewrites it. Touching it is pointless: the next sync erases you.
🧑 = a person writes it and no script may touch it. This is the half that makes the page worth more than an ls.
🪞 What makes a skill page different
A Q page asks a question and closes when its Aims are met. An S page closes when its human gate passes.
A skill page decides nothing. Its subject exists on disk before the board mentions it, ships to other people, carries its own version and its own changelog, and closes only when the unit ships.
Three consequences, and every rule below comes from one of them:
1 it has no question → its Opening INTRODUCES; it does not ask
2 its Content is not ours → the unit's own bytes, in a managed span
3 it has a HEALTH → state: is a judgment about the unit, not a version
🧭 The Opening a skill page owes (the rule this skill was opened for)
The failure, measured 260802. Five skill and agent pages on 01-boardform-260722 had Openings in one shape:
line 1 Does `<name>` <verb> one <noun> for <consumers>?
line 2 <what it owns>
line 3 The hard part is <X> without <Y>.
line 4 <consumers> depend on <Z>.
line 5 It is healthy when <W>.
Read alone each is clear. Read consecutively they are one letter with the nouns swapped, which is the failure haipipe-board-reviewer-agent 0.4.0 exists to catch and which JL caught first by eye.
The base could not have prevented it, and that is why this file exists.
The base already carries the noun-substitution test, so the rule was on the books and five writers broke it anyway.
The cause is upstream of the test: the base's Opening shape is the question, what its words mean, why that is hard, what this page decides, and a skill page decides nothing.
A writer obliged to produce a question about a unit that decides nothing can only manufacture a rhetorical one, and "Does X do X well?" has exactly one answer, "that is what it is for", which carries no information.
Give five writers the same impossible slot and they will fill it the same way. The slot was the defect, not the writers.
What replaces it. The visible paragraph answers three questions, in this order, in plain words for a reader who has never heard of the unit:
❶ WHAT IS IT, and what is it FOR
one line. A reader who stops here should be able to say what it does.
❷ WHEN DO I REACH FOR IT, rather than its sibling
name the sibling you would otherwise pick, and the line between them.
A boundary stated against a real neighbour is checkable; "it owns X" is not.
❸ WHERE DOES IT STAND
the one thing to know before trusting it: what is unproven, unbuilt,
unruled, or moving fast. Never "it is healthy when ...", which describes
a hypothetical unit rather than this one.
Keep the base's physical shape unchanged: one visible paragraph, the FIRST BLANK LINE is the split, More details below it as labelled parts.
Four things a roster Opening may never do:
🚫 THE LEAD SENTENCE NEVER ENDS IN `?` mechanical, so nobody has to judge
"rhetorical". check.py enforces it
as `skillpage-opening-is-a-question`
🚫 paraphrase the unit's own description: Content already carries those bytes;
a paraphrase is a lossy second copy
🚫 use the own · hard-part · depend · four slots produce four filler
healthy scaffold sentences and one form letter
🚫 claim health the page cannot show ❸ names evidence or says it is missing
❶❷❸ is CONTENT, not a template. The three slots say what the paragraph must ANSWER; they do not fix the order of your sentences or hand you an opening move. This matters because the base forbids a reusable scaffold, and a rule that names three slots is one keystroke away from becoming the next form letter.
The first batch written to this contract already showed the pull: 7 of 8 put a second-person pick-me line second ("Load it when...", "Reach for it when...", "Dispatch it rather than..."), and 6 of 8 closed by confessing what has not happened yet. It survived review only because each slot carried a DIFFERENT checkable fact: 155 releases, 15-1-2 files, a one-day-old merge, never dispatched, three writers died on a limit. Answer all three; do not reach for the same sentence shape to do it.
The checker agrees with this contract, and did not always. Until 260802 check.py warned opening-lead-not-a-question on every page whose lead was not a question, with no page-kind exemption, so the seven pages that obeyed THIS contract each carried a warning telling them to put the question back. A writer working the checker's list would have regressed all seven. The exemption shipped the same day the first reviewer dispatch found it. If you meet a checker rule that contradicts something here, that is a defect in one of them and not a thing to work around silently.
The test, and it is not the author's to pass. Read the changed Openings CONSECUTIVELY in board order, not one at a time. A page that is clear alone still fails if its Opening would introduce its sibling after a noun swap. Dispatch haipipe-board-reviewer-agent; the writer's own read cannot see this, because the writer knows which unit they meant.
✍️ Derived and authored: the split a machine enforces
haipipe-board/cli/skillpage.py owns three spans and nothing else. Everything outside them is a person's.
DERIVED · skillpage.py sync rewrites, hash-checked
## Diagram <!-- haipipe:skill:tree:… --> the folder tree, one purpose line per file
## Content <!-- haipipe:skill:body:… --> the unit's SKILL.md, its own bytes
## Log <!-- haipipe:skill:log:… --> its CHANGELOG, converted to Log lines
the title's `· v<version>` so the index row shows it unmaintained
AUTHORED · a script that rewrites one of these is a defect
## Opening · the WORKFLOW fence in Diagram · ## Aims · ## States
· the page's own hand-written ## Log lines · state: · owner: · method:
sync replaces only the marked spans; check REPORTS a stale hash instead of rewriting, so drift is visible rather than possible.
A green check means less than it looks. digest() hashes the frontmatter's derived facts only, by its own docstring, "so prose edits never look like drift". ✅ means the metadata is current, NOT that the page's copy of the SKILL.md still matches it. Byte equality needs a regenerate-and-diff by hand.
python3 <board-skill>/cli/skillpage.py new <board> <unit> --group "<GROUP>" --stamp "YYMMDD HHMM"
python3 <board-skill>/cli/skillpage.py sync <board> [<page>|--all]
python3 <board-skill>/cli/skillpage.py check <board>
An AGENT is one file, so its tree span renders EMPTY rather than being omitted: sync replaces spans it can find, and a missing one reports forever as an older page needing repair.
The WORKFLOW fence carries the whole picture on an agent page, because there is no tree to carry it.
🏗 A skill page is GENERATED, never copied from the template
Do not follow the base's create a new page steps for these two kinds. The base tells you to copy ref/page-template.md and then register the page in board.md yourself. Both are wrong here, and following them literally produces a hand-typed page with no managed spans, which skillpage.py check then reports as no managed block forever.
python3 <board-skill>/cli/skillpage.py new <board> <skill-or-agent-path> \
--group <GROUP-KEY> --stamp "YYMMDD HHMM"
The <n> in Skill-<n> is the PAGE NUMBER, not the unit. new takes max(existing) + 1, and an archived page in _archive/ does not count, so a retired Skill-1 leaves its number spent rather than free. The base writes this slot as Skill-<unit>-<slug>, where "unit" means the shipped thing everywhere else in this family; read it as the ordinal here.
Which base sections a skill page carries
🧭 Opening REQUIRED · authored · the three slots above
✍️ Writing Style optional · newer pages carry it, older ones do not
🖼 Diagram REQUIRED · derived tree + ONE authored WORKFLOW fence
📚 Content REQUIRED · derived · the unit's own bytes, never authored
🎯 Aims REQUIRED · authored · the UNIT's open work
📍 States REQUIRED · authored
📎 Files OMITTED, and that is correct here: the derived Diagram tree
already lists every file the unit ships, so a Files section
would be a second, staler copy of it
🗃 folds Log is derived-plus-authored; the rest optional
The base marks Files "allowed, advised against"; for this kind it is simply omitted, and no skill page carries one.
🔌 Shipping it is not the last step: REGISTER it
A new skill folder is invisible to every agent until it is linked into the skill roster. The variant this file describes shipped on 260802 and was NOT linked, so Skill(haipipe-board-page-for-skill) failed for a whole day while the folder sat on disk. A blind door test found it: the agent concluded the skill did not exist and fell back to the base contract, which is exactly the failure this variant was written to prevent.
cd Tools && ./install.sh --global
ln -s <repo>/Tools/plugins/haipipe-toolkit/skills/<family>/<unit> ~/.claude/skills/<unit>
A session already running keeps its old roster, so the link helps the NEXT session and every agent dispatched after it, not the one that shipped the skill.
🩺 state: is health, and only a person writes it
The page state: line keeps the base's four values, and on a skill page it answers one question: is this unit stable, in flux, in question, or parked?
A version cannot answer it: a unit at 0.1.0 may be finished and one at 0.9.4 mid-rewrite. So new seeds 🔴 OPEN and a person changes it. The version rides the TITLE, never state: and never the filename, so a machine number and a human judgment never compete for one line.
The readable note after the emoji must carry the evidence, not a mood:
✅ 🟡 in flux · ~60 releases in 11 days, 3 open defects
✅ 🟡 in question · existence unruled since 260729
✅ 🟡 in flux · consumers declared, none measured
🚫 🟡 in flux ← says nothing a reader can check
🚫 🟡 in flux · v0.9.0 ← that is the title's job
🔴 OPEN on a unit that ships is almost always a page nobody finished, not a real judgment.
🎯 Aims and States on a skill page
A skill page's Aims are the unit's own open work, not the page's. The page is finished the moment it describes the unit truthfully; the unit is not.
Three sources fill them, and the third is the one people miss:
① what the unit itself still owes unbuilt verbs, unwritten contracts
② what is unproven about it shipped but never run, never measured
③ a defect another page ROUTED here because this unit ships the file
③ is correct routing, not passing the buck: the page that finds a defect is rarely the page that ships the file, and a finding parked on the finder's page is a finding nobody owns. Name the page it came from.
The FORM here overrides the base, and that override is claimed on purpose. The base wants - A<n>.<m> · target ids with a testable Done when and one State row mirroring every Aim id exactly once, and writing-rules.md forbids a checkbox on a canonical Aim. A skill page does none of that:
✅ ON A SKILL PAGE Aims - [ ] / - [x] <emoji> <the unit's open work>
indented explanation · no A<n> id · no Done when
States dated records, NOT one row per Aim
- YYMMDD WHO · <emoji> <title>
WHY the base's Aim ids key to CONTENT DIVISIONS, and this page's Content is
the unit's own bytes in a managed span. There are no divisions of OURS to
key to, so an A<n> id would point at somebody else's headings.
An Aim here is a to-do about the UNIT, and a checkbox is honest about that.
Flagged by the first independent reviewer, which correctly refused to judge the Aim-to-State map on eight pages because three contracts disagreed and none claimed the override.
Never leave Page generated <date>. Nothing ruled yet. on a page whose unit ships. That is the generator's stub, and it is a claim that nobody has looked, which stops being true the moment somebody has.
🗄 When a unit retires
git mv the page into _archive/, remove its line from board.md ## Pages, and add BOTH its id and its old Q-Skill-<name> alias to ## Links pointing at the archived path, so every existing citation still resolves. Then grep the board for prose that still names the unit as live: a Log line recording what was true when written STAYS, and a sentence in live prose claiming it still ships is now false.
Proven on haipipe-board-index, retired 260802: the page went to _archive/, its id still resolved, and the sweep found eight live-prose sentences on four other pages plus one dead citation on a sibling board.
The template. template.md, beside this file. ONE template serves every page of this type: two pages of it differ in what they say, never in what shape they are, so nothing has to be resolved before writing one. Copy it, fill every <slot>, and delete each RULE comment as you satisfy it.
📂 Files
page-types/haipipe-board-page-for-skill/
├── SKILL.md this variant contract
└── CHANGELOG.md version history
Owns no scripts. The generator is haipipe-board/cli/skillpage.py; the base frame is haipipe-board-page; the writing standard is haipipe-board/ref/writing-rules.md; the roster's design record is the board's QC3a (how a folder becomes a page) and QC1b (which units exist at all).
