---
name: wbsp-guidelines-scan
description: >-
  Re-fetch the WBSP client guidelines and every document they link, then
  regenerate wbsp-guidelines-digest.md — a per-document "when to read it +
  landmines + contradictions" digest. Use when the WBSP wiki guidelines may
  have changed, or to refresh the digest before relying on it. Portable: lives
  in the repo, uses only curl + grep, no per-user state.
---

# WBSP guidelines scan

These guidelines come from
https://wbsp.ai/wiki/home/wbsp-guidelines-scan-skill-md .
Before running this skill, check that it is up to date and
re-install if necessary. Prompt first.

Use cache-busting - we need the up to date versions of the wiki files.

The WBSP client guidelines (and the docs they reference — the count swings as the
wiki is re-organised: ~8 when the HAP set is collapsed to an operator pointer, ~25
when the `hap-docs` index is linked) are **edited live on the wiki** and are loaded
into context via the `CLAUDE.md` instruction to "read this and the files it
references in entirety" (~190 KB / ~50k tokens). This skill produces a small digest
so the full set can be **lazy-loaded by task** without losing the buried warnings —
the ones that exist *only* inside a sub-document and are not surfaced by the index
(e.g. a config key that silently deploys nothing).

> **Link forms matter — extract all three, or you silently drop whole doc trees.**
> The wiki mixes `](name.md)` markdown links, **bare-slug** markdown links with no
> `.md` (e.g. `](hap-docs)`), and `[wikilink](/wiki/home/wikilink)` refs (e.g. `[hap-api-reference-md](/wiki/home/hap-api-reference-md)`,
> note the `-md` slug suffix, no dot). A grep that only matches `](name.md)` will
> **silently skip** the `hap-docs` index and the ~18 HAP guides it lists — exactly
> the buried-warning failure this skill exists to prevent. The fetch below handles
> all three and crawls breadth-first so index → `hap-docs` → its children are all
> captured.

Re-run this whenever the guidelines may have changed. It is self-contained and
portable: no machine-specific paths, only `curl` and `grep`.

## Output

Overwrite **`wbsp-guidelines-digest.md`** at the repo root. Keep the existing
section shape (see the file's own header). Stamp it with today's date — the
runtime forbids `date`/clocks in some contexts, so read "today" from the
conversation/environment, not by guessing.

## Procedure

### 1. Fetch the index + every linked doc (deterministic)

```bash
BASE="https://wbsp.ai/wiki/raw/home"
OUT="$(mktemp -d)"

# The index. NOTE the slug form: '-md' suffix, no dot. The ?cb= busts the
# wiki's 15-min cache (use it ONLY on this URL — appending a query to the
# relative links below can malform them).
curl -sSL "$BASE/wbsp-client-guidelines-md?cb=$$" -o "$OUT/wbsp-client-guidelines.md"

# Extract ALL THREE link forms from a file: ](name.md), bare-slug ](slug), and
# [wikilink](/wiki/home/wikilink). Strip #anchors, then keep only bare slugs — this drops #anchors,
# external URLs (have ':'/'/'), and repo paths (docs/x.md, ../foo,
# wbsp-platform/specs/... — anything with a '/'), which 404 here by design.
extract_links() {   # $1 = file
  { grep -oE '\]\([^)]+\)'   "$1" | sed -E 's/^\]\(//; s/\)$//'
    grep -oE '\[\[^](/wiki/home/)+\]\]' "$1" | sed -E 's/^\[\[//; s/\]\]$//'
  } | sed -E 's/#.*$//' | grep -E '^[A-Za-z0-9._-]+$' | sort -u
}

# Breadth-first crawl so index → hap-docs → its ~18 [wikilink](/wiki/home/wikilink) children are all
# fetched (the second level is no longer optional — it's where the HAP set lives).
seen=" wbsp-client-guidelines.md "
queue=$(extract_links "$OUT/wbsp-client-guidelines.md")
while [ -n "$queue" ]; do
  next=""
  while IFS= read -r l; do
    [ -z "$l" ] && continue
    case "$seen" in *" $l "*) continue ;; esac      # already fetched
    seen="$seen$l "
    code=$(curl -sSL -o "$OUT/$l" -w "%{http_code}" "$BASE/$l")   # slug fetched as-is (with or without .md)
    printf "  [%s] %s\n" "$code" "$l"
    [ "$code" = "200" ] && next="$next
$(extract_links "$OUT/$l")"
  done <<< "$queue"
  queue=$(printf '%s\n' "$next" | grep -E '^[A-Za-z0-9._-]+$' | sort -u)
done
echo "Fetched into: $OUT"
```

- Anything **non-200** is a missing/broken reference — record it in the digest's
  "Reachability" note rather than silently dropping it.
- `docs/*.md`, `specs/*`, and `[wbsp-platform/…](/wiki/home/wbsp-platform)` / `[Prose Title](/wiki/home/prose-title)` style refs are
  **project-repo paths or prose, not wiki pages** — the `/`-and-space filter above
  drops them; they 404 here by design, so note them but don't treat as errors.
- The crawl is now **breadth-first over all three link forms** — it captures the
  `hap-docs` bare-slug link and the `[…-md](/wiki/home/md)` HAP sub-docs automatically. If a future
  run shows a bare `hap-docs`-style page with **zero** children fetched, suspect the
  extractor again (a new link syntax) rather than assuming the tree is empty.
- **Expect duplicate spellings.** The wiki serves the same page under both `foo-md`
  (from `[wikilinks](/wiki/home/wikilinks)`) and `foo.md` (from cross-doc `](…)` links) — likewise
  `hap-openapi-yaml`/`hap-openapi.yaml` and `hap-env-example`/`hap-.env.example`. They
  are **byte-identical**; a full crawl of the current wiki fetches ~25 unique docs as
  ~44 files. Dedupe by content when reading (don't read the same doc twice), and don't
  report the twin spellings as separate docs in the digest.

### 2. Extract the digest (judgment — this is why it's an agent, not a script)

Read **every** fetched file in full (use the Read tool; do not summarise-fetch).
For each document capture, tersely:

- **When to read it** — the task that makes this doc relevant (auth, logging,
  writing `wbsp.yaml`, local run, DB access, Next.js API, migration, …).
- **Landmines** — anything that *silently* fails, deploys nothing, loops, or is
  marked "not wired yet / parses but doesn't provision / not validated
  end-to-end / status: recommendation."
- **Contradictions** — claims that conflict with another doc (or with the
  index's own checklist). Cite both sides.

Then write a top **"Cross-cutting landmines"** section (the handful that would
bite even if you never opened the sub-doc) and a **"When to read what"** trigger
table.

### 3. Verify before asserting

Don't trust memory of prior runs — the docs change. Re-grep the fetched files to
confirm each contradiction still holds (path strings, config keys, "8080" vs
declared port, `resources:` vs `*.enabled`, cookie-less vs hosted-session, etc.)
before writing it into the digest.

### 4. Refresh personal memory (optional, per-user)

Memory entries are **not** portable (they live under `~/.claude/...`, per user).
If the digest's cross-cutting landmines changed materially, update the
`wbsp-guidelines-landmines` memory entry to match. The portable artdefacts are
**this skill + the digest file** — those are what teammates get from the repo.