board-snapshot

Files (31)

• SKILL.md
• why-these-rules.md · references/
• expected.md · self-test/01-ceiling-breached/
• manifest.json · self-test/01-ceiling-breached/
• expected.md · self-test/02-two-empty-sections/
• manifest.json · self-test/02-two-empty-sections/
• expected.md · self-test/03-blocker-unrecorded/
• manifest.json · self-test/03-blocker-unrecorded/
• expected.md · self-test/04-open-card-in-done/
• manifest.json · self-test/04-open-card-in-done/
• expected.md · self-test/05-page-dropped/
• manifest.json · self-test/05-page-dropped/
• expected.md · self-test/06-slice-cards-inflate/
• manifest.json · self-test/06-slice-cards-inflate/
• expected.md · self-test/07-card-with-no-status/
• manifest.json · self-test/07-card-with-no-status/
• expected.md · self-test/08-all-drops-nothing/
• manifest.json · self-test/08-all-drops-nothing/
• expected.md · self-test/09-title-is-not-a-description/
• manifest.json · self-test/09-title-is-not-a-description/
• expected.md · self-test/10-all-cannot-clip/
• manifest.json · self-test/10-all-cannot-clip/
• expected.md · self-test/11-empty-card-body/
• manifest.json · self-test/11-empty-card-body/
• expected.md · self-test/12-handles-in-a-description/
• manifest.json · self-test/12-handles-in-a-description/
• expected.md · self-test/13-mandatory-sections-exceed-the-ceiling/
• manifest.json · self-test/13-mandatory-sections-exceed-the-ceiling/
• expected.md · self-test/14-open-issue-off-the-board/
• manifest.json · self-test/14-open-issue-off-the-board/
• README.md · self-test/

SKILL.md (first lines)

# Board snapshot — where the board stands, not what is wrong with it

A board in perfect shape still costs a full read. Every other command over a board answers a different
question and answers it at length. This one answers *where does it stand*, and stops.

**GitHub Projects v2 only.** GitLab is not implemented and is not stubbed: its boards express a column as
a scoped label rather than a project field, so the items query below has no counterpart there. Say so and
stop rather than approximating.

**REQUIRED BACKGROUND: `phil:issue-board`.** Every forge mechanic — `-R` targeting, Status as a project
field, GraphQL over `item-list`, the board constants in a project's `CLAUDE.md` — lives there. Do not
guess any of it here.

## The routing this skill exists to win

**Keep these apart, out loud, whenever more than one could be intended.** The measured failure that
produced this skill is in `references/why-these-rules.md`.

| Question | Command |
|---|---|
| Where does the board stand? | **this one** |
| What is wrong with the cards? | `phil:groom-issues` |
| What order should these be in? | `phil:rank-issues` |
| What is happening inside one card? | `phil:nwave-slice-status` |
| What was *I* doing? | `phil:resume` |
| What did the finished thinking decide? | `phil:nwave-wave-summary` |

## The read — shared by both modes

**One call for the board.** Status is a project field, so this is a project-items query and never
`gh issue list`, which returns no Status at all, for the board read; `gh issue list` serves only the
reconciliation below.

**Branch on the owner's type first.** `user(login:)` errors with `Could not resolve to a User` against an
organization-owned board, and `organization(login:)` errors the same way against a personal one. There is
no form that serves both, so resolve the owner and pick — `${CLAUDE_PLUGIN_ROOT}/scripts/probe-board.py`
already branches this way and is the reference.

```sh
gh api graphql -f query='{ repositoryOwner(login:"<owner>"){ __typename } }'   # User | Organization
```

**Send the document with GraphQL variables, never interpolated into the query string.** An inline
`-f query='… fieldValueByName(name: "Status") …'` fails to parse on nested quotes, and a command cannot
write a temp file inside its grant. Substitute `user` or `organization` for the root field; everything
after it is identical.

```sh
gh api graphql -f query='query($o:String!,$n:Int!,$f:String!){ user(login:$o){ projectV2(number:$n){
  items(first:100){ nodes { id content { ... on Issue { number title state url } }
    fieldValueByName(name:$f){ ... on ProjectV2ItemFieldSingleSelectValue { name } } } } } } }' \
  -f o=<owner> -F n=<project-number> -f f=Status
```

**Items arrive in board-position order and that order is authoritative.** Consume it. Never sort, never
re-rank, never infer an order from labels or dates — `phil:rank-issues` is the one surface that produces
an order, and a second producer makes neither answer trustworthy.

**Read the board constants from the target repo's `CLAUDE.md`.** Never probe for them; `phil:board-setup`
owns writing them.

**Paginate rather than truncate.** A `first:100` that returns a cursor is a partial read until the next
page is fetched. See *Partial reads*.

### The project holds only what was added to it

**A `projectV2` items query returns cards, and an issue reaches the board only by an explicit
`gh project item-add`.** An open issue nobody added is invisible to the query — so a read whose whole
purpose is saying what is there would omit it in silence, which is the completeness failure *Partial
reads* forbids, arriving structurally rather than through a dropped page.

**So reconcile, in one more call**, and report the difference rather than absorbing it:

```sh
gh issue list -R <owner/repo> --state open --json number --limit 200
```

Any open issue not among the project's items is **off the board**. Report the count in one line, name
`phil:issue-board` for adding them, and add nothing.

## Mode 1 — the standing check

The default. Three sections, in this order, always: **blocked**, **in flight**, **queued**.

- **Blocked** — every card, each naming what it waits on or saying the blocker is unrecorded.
- **In flight** — every card. No cap; a board with many is telling the reader something.
- **Queued** — the first *N* in board order. **N defaults to 5** and is set by `--next N`.

**Say where the order came from.** One clause: the queued cards are the forge's own order, not this
command's.

### Blocked cards need a second, small read

The forge records that a card is blocked; the reason lives in prose. Read the `## Chain` section of each
blocked card's body and quote what it waits on.

```sh
gh issue view <n> -R <owner/repo> --json body
```

**One call per blocked card, and blocked cards are few.** **Where a blocked card carries no `## Chain`
line, say the blocker is unrecorded.** Never infer one from a title, a label or an adjacent card.

### The ceiling

**200 words, counted over the whole rendered output, including every report line.**

**Where the ceiling would break, print fewer queued cards and state how many were withheld.** Count the
withheld against the whole queued population, not against N — a reader who asked for five and got three
needs to know whether thirty-seven are waiting or two are. Never truncate in silence.

**Blocked and in-flight cards are never dropped to fit.** Only the queued section gives ground.

**When the two rules collide, the ceiling yields and the run says so.** Blocked and in-flight cards alone
can exceed 200 words on a badly stuck board. Then zero queued cards still breaches, and there is no
satisfying both — so print every blocked and in-flight card, breach the ceiling, and state that the
mandatory sections exceeded it. **Dropping a blocked card is the worse failure**, because the blocked
section is the one a reader trusts most, and a silent overrun would be worse than both.

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin