board-setup

Files (32)

• SKILL.md
• drift-and-retire.md · references/
• gitlab.md · references/
• outcomes.md · references/
• provenance-model.md · references/
• expected.md · self-test/01-fresh-target/
• manifest.json · self-test/01-fresh-target/
• expected.md · self-test/02-refused-probe-writes-nothing/
• manifest.json · self-test/02-refused-probe-writes-nothing/
• expected.md · self-test/03-section-already-exists/
• manifest.json · self-test/03-section-already-exists/
• expected.md · self-test/04-malformed-markers/
• manifest.json · self-test/04-malformed-markers/
• expected.md · self-test/05-region-already-present/
• manifest.json · self-test/05-region-already-present/
• expected.md · self-test/06-contradicting-line/
• manifest.json · self-test/06-contradicting-line/
• expected.md · self-test/07-cannot-evaluate-is-not-an-offer/
• manifest.json · self-test/07-cannot-evaluate-is-not-an-offer/
• expected.md · self-test/08-decline-leaves-unevaluated/
• manifest.json · self-test/08-decline-leaves-unevaluated/
• expected.md · self-test/09-declaration-contradicts-evidence/
• manifest.json · self-test/09-declaration-contradicts-evidence/
• expected.md · self-test/10-rerun-writes-zero-bytes/
• manifest.json · self-test/10-rerun-writes-zero-bytes/
• expected.md · self-test/11-gitlab-unread-labels/
• manifest.json · self-test/11-gitlab-unread-labels/
• expected.md · self-test/12-vanished-option-id/
• manifest.json · self-test/12-vanished-option-id/
• expected.md · self-test/13-retire-must-not-reach-a-declaration/
• manifest.json · self-test/13-retire-must-not-reach-a-declaration/
• README.md · self-test/

SKILL.md (first lines)

# Board setup — probe, label, write

Discover a repo's board constants and write them down **before** they are learned by contact.

Probe everything discoverable, ask for what is not, and **label every line with where it came
from**. A line whose origin cannot be told is the defect here — not a line that is missing.

Why that is the thesis, and why this plugin's own `CLAUDE.md` is the evidence for it:
`${CLAUDE_PLUGIN_ROOT}/skills/board-setup/references/provenance-model.md`.

## Three categories, and every fact line carries one

| Category | Means | Where it is written |
|---|---|---|
| **probed** | the forge returned it | **inside** the markers |
| **assumed** | the forge returned *half* of it, or it is derived from a proxy | inside the markers, labelled, saying what is not knowable |
| **declared** | only a human can say it | a **separate** region, attributed, never regenerated |

**No line in either region is composed at run time, so no prose standard applies to a session here.**
Every line — `probed`, `assumed` and its *not knowable … why* clause alike — is emitted by
`render-block.py` from strings that live in `probe-board.py`. A session that composed one would be
typing a value the script returns, which *Never type a value this script could return* forbids and
*Hand-writing a region breaks determinism* explains the cost of.

**The rationale strings are still prose**: `rules/writing.md` governs them at build time, in
`probe-board.py`, for whoever edits them.

**`declared` is out for a second, independent reason**: a human wrote it, and judging prose a human
wrote is taste.

The third category is not decoration: *"Auto-close on Done is ENABLED"* is one confident sentence
spanning a fact and a guess, because the forge reports that the workflow is on and never which
status fires it. The field-level derivation is in `${CLAUDE_PLUGIN_ROOT}/skills/board-setup/references/provenance-model.md`.

## The probe is a script, and that is the point

Run `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/probe-board.py --repo OWNER/REPO`. It emits JSON: every
value paired with the exact query that produced it, in a fixed field order.

**Never type a value this script could return, and never fill a gap it left.** A value that did not
come out of the JSON does not go inside the markers, because in the finished file a remembered id is
indistinguishable from a probed one.

**Read `status` first.** On `refused`, **write nothing** and report `refusal.reason`, then
`refusal.fix` **when it is non-null** — `fix` is nullable, and printing `None` at a reader is worse
than saying no fix is known. A refusal whose reason names an unbuilt slice is reported as *not
available yet*, never as an instruction: there is no flag that names a board, and relaying advice the
product cannot honour is its own defect.

A partial block is worse than none: a block silently missing its Status field id reads exactly like
one whose board has no Status field.

## The region

```markdown
## Issue board

<!-- phil:board-setup:v1:begin -->
generated 2026-08-17T14:44Z · do not edit inside these markers

- Forge: GitHub at github.com — use `gh -R owner/repo` on every call *(probed · Q1)*
- Board: project `PVT_…` · number 3 · "phil plugin" *(probed · Q2)*
- Status is a project **field**, id `PVTSSF_…` — not a label *(probed · Q3)*
- Status options (4) *(probed · Q3)*: Todo `f75ad846` · In Progress `47fc9ee4` · …

**Queries**

- `Q1` — `gh repo view owner/repo --json nameWithOwner,defaultBranchRef,isFork,isPrivate`
- `Q2` — `{ repository(owner:"…", name:"…"){ projectsV2(first:20){ … } } }`

<!-- phil:board-setup:v1:end -->
```

**The markers are bare and versioned; the timestamp is the first line inside**, so the string a
refresh matches on never changes between runs.

**Every bullet names the query that produced it**, with the queries listed once each at the foot —
several constants come from one call, and repeating a GraphQL document per bullet buries the values
it exists to source. Two shapes need a rule:

- A fact whose `query` is a cross-reference (`"(see project-discovery)"`) cites the **referenced
  fact's** Q-number.
- A compound `query` — two calls joined because the first returned nothing — becomes **two** named
  entries, with what the first returned recorded.

**Everything outside the markers belongs to a human, permanently.**

### The facts with no template field still get written

Five facts carry no `template_field`: `default-branch`, `fork`, `project-discovery`, `board-view`,
`other-single-select-fields`. **They are not surplus and must not be dropped.** Write them as
bullets in the same region, after the template-shaped ones, each carrying its provenance and
Q-number like any other. `fork` and `other-single-select-fields` appear only when the forge returned
them. Why *how the board was found* is itself a constant: `${CLAUDE_PLUGIN_ROOT}/skills/board-setup/references/provenance-model.md`.

## Two regions, and the second is a human's

A declaration lives in a **second delimited region**, outside the probed markers, so the probed region
can be regenerated without touching a human's answer:

```
<!-- phil:board-setup:declared:v1:begin -->
generated … · declarations, not probed facts — a human's answers
- Label family **wave** (`wave: discuss`): **single-valued** *(you declared · 2026-08-17)*
<!-- phil:board-setup:declared:v1:end -->
```

- The **probed** region is regenerated freely, every run.
- The **declared** region is written once on an answer and **never regenerated**. A second
  `--declare` refuses.

**Every ask that fills the declared region follows `${CLAUDE_PLUGIN_ROOT}/skills/shared/decision-request.md`.**
Load it before the first `AskUserQuestion` call.

Two things that standard cannot know: what makes a question *un-probeable* is this skill's own finding,
so the context block carries the probe that failed and why no forge answers it; and the counted ask must
describe the convention in plain terms — a question about label families that names the families as
identifiers is asking the reader to hold the vocabulary the answer is supposed to establish.

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin