Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions .claude/skills/code-hotspot-analysis/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,10 @@ This is a **prioritization** tool, not a judgment tool. It tells you where to po

Run all of these against the whole repo or a suspect package; save `dot`/`svg`/`.puml` output somewhere durable if the finding is worth referencing later (this repo's convention: `docs/architecture-audit-<date>.md` plus any generated artifacts alongside it).

**Check kibitzer first.** If the repo has a `.claude/inspect.json` and `kibitzer` is on `PATH`
(or its MCP server is connected — same underlying tool, use whichever this session has), it
covers most of the table above with no per-repo tool install:
**Check kibitzer first.** If `kibitzer` is on `PATH` (or its MCP server is connected — same
underlying tool, use whichever this session has), use it. It covers most of the table above with no
per-repo tool install and no per-repo config (see the throwaway-worktree note below if the tool asks
for an `inspect.json`):

| Signal | kibitzer command | Covers | Doesn't cover |
|---|---|---|---|
Expand All @@ -34,9 +35,23 @@ covers most of the table above with no per-repo tool install:
| Complexity | Same `kibitzer run --trigger batch` output as row 1 — filter for `long-function` (>40 lines), `deep-nesting` (>4 levels) | A real, zero-install signal for ranking hotspots. Go/TS/TSX/JS/Python/Java/Kotlin. | Not true cyclomatic/cognitive complexity, just a line-count/nesting heuristic — use `gocyclo`/`gocognit` when you need the actual metric, not just a ranking |
| One symbol's exact definition | CLI: grep the `architecture export` JSON for the symbol id — MCP: `get_architecture_node` (`node: "<pkg>::<Type>.<Method>"` or a package path) | Single lookup, no repo-wide grep | Same Go/TS/TSX/JS limit as the row above |

Fall back to the Go-specific toolchain below only when kibitzer isn't configured for this repo,
or a finding genuinely needs a real call graph, a true cyclomatic/cognitive number, or symbol-level
detail in a language kibitzer's symbol export doesn't cover yet.
**Never skip kibitzer because the repo has no `.claude/inspect.json`, and never hand-roll a
complexity counter.** Today the MCP tools fail on such a repo with `no .claude/inspect.json found above this path` (tracked in
[kibitzer#168](https://github.com/tstapler/kibitzer/issues/168), which asks for built-in defaults). Until that
lands: `git worktree add --detach /tmp/<repo>-kib origin/main`, write `{}` to
`/tmp/<repo>-kib/.claude/inspect.json`, and point the MCP tools at that throwaway worktree (never
commit the file into the repo under analysis). With the empty config it runs the default checks and the
output is the same as a configured repo. Verified on a Go service: `architecture_assessment` with
`scope: "pkg/x/**"` and `include_diagram: false` returned 188 findings across 123 files in one call, and
its biggest function (998 lines) matched a hand-written AST counter's number for the same function. Redirect or filter the output
(it is long): group findings by file and rank by `long-function` body size, `deep-nesting`, and
`long-parameter-list`. Then add churn from `git log --since=6.months --name-only`. Reach for
`gocyclo`/`gocognit` only if you need a true cyclomatic number.

Fall back to the Go-specific toolchain below only when kibitzer isn't available in this session
(and the throwaway-worktree workaround above isn't possible), or a finding genuinely needs a real
call graph, a true cyclomatic/cognitive number, or symbol-level detail in a language kibitzer's symbol
export doesn't cover yet.

**Working commands and gotchas actually hit running this stack** (Go 1.25, this repo):

Expand Down
17 changes: 9 additions & 8 deletions .claude/skills/design-doc-review/skills/outline/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
description: Check a design doc / RFC's structure against the required topic set (problem, non-goals, alternatives, risks, rollout) AND verify every open question/decision ask names a decider, deadline, and default-if-silence. Flags missing or weak sections. One check in the design-doc-review pipeline — run standalone or via design-doc-review:review.
description: Check a design doc / RFC's structure against the required topic set (problem, non-goals, alternatives, risks, rollout) AND verify every open question/decision ask is a concrete decision with a reason to decide it, in a readable format. Flags missing or weak sections. One check in the design-doc-review pipeline — run standalone or via design-doc-review:review.
---

# design-doc-review:outline
Expand Down Expand Up @@ -36,13 +36,14 @@ The whole point of a design doc review is a room full of people's time spent ext
For **every** open question, decision request, or "needs review input" flag in the doc (usually but not always in an Open Questions / Decision Needed section):

- [ ] It is phrased as a concrete decision, not a topic — "should we scope this to Alternative B or the full process?" not "there's some ambiguity about scope"
- [ ] It names who decides (a person, a role, or "this review") — not left implicit
- [ ] It states a deadline or trigger ("before Wk 0 starts", "by end of review") — not open-ended
- [ ] It states a default-if-silence — what happens if nobody answers by the deadline. Absence of a default is what turns a question into permanent bikeshedding.
- [ ] Blocking questions (ones that gate the rest of the doc/plan) are visibly distinguished from informational ones — a reader shouldn't have to guess which of five "Open Questions" is load-bearing
- [ ] It says **why it needs deciding**: what it blocks, or what goes wrong if it's left open. A reader should learn the stakes from the text, not infer them from the question.
- [ ] It states a recommendation when the author has one, and what happens if nobody objects (the default). Absence of a default is what turns a question into permanent bikeshedding.
- [ ] It is NOT required to name a named decider or a deadline. Many teams don't work that way, and a ritual "owner / due date" cell reads as process theater. Flag a missing owner or date only if the doc's own surrounding text says one matters.
- [ ] Blocking questions (ones that gate the rest of the doc/plan) are visibly distinguished from informational ones, best done by grouping the asks by what they block ("Needed before stage 1"), not by a column
- [ ] The set of asks is complete and non-redundant — every genuine decision point the doc raises anywhere in its body (not just ones the author happened to list) shows up in this set once, in one place, not scattered
- [ ] **Format:** each decision is a short headed section with one or two short paragraphs, not a row in a wide table. A table is fine for short, parallel facts. It is the wrong shape when cells hold sentences. See `../../../writing/CHECKLIST.md` ("Long prose in table cells") for the sources.

This is the same "Decision requested" pattern `design-doc-review:readability` looks for in the main body (numbered asks, one owner, one default-if-silence, each per row) — that skill flags *prose* burying the ask; this check verifies the ask actually *exists* and is *complete* as a structural matter, independent of how well it reads.
This is the same "Decision requested" pattern `design-doc-review:readability` looks for in the main body (numbered asks, a reason to decide each, one default each) — that skill flags *prose* burying the ask; this check verifies the ask actually *exists* and is *complete* as a structural matter, independent of how well it reads.

## Checklist

Expand All @@ -55,7 +56,7 @@ This is the same "Decision requested" pattern `design-doc-review:readability` lo
- [ ] L3: Operational concerns addressed
- [ ] L3: Rollback / reversal plan stated
- [ ] L3: Prior org decisions acknowledged
- [ ] Decision Ask: every open question/decision request names a decider, a deadline, and a default-if-silence (see Decision Ask section above)
- [ ] Decision Ask: every open question/decision request is concrete, says why it needs deciding, and gives a recommendation or default (see Decision Ask section above). No decider/deadline required
- [ ] Decision Ask: blocking vs. informational questions are distinguishable, and the set is complete/non-redundant
- [ ] Doc is not too long to read in one sitting for its stakes — if it is, does it push detail to an appendix rather than the main body (see the Proportionality note in CLAUDE.md: comments/PRs/docs should carry only what a reviewer of *this* artifact would ask for)

Expand All @@ -82,7 +83,7 @@ Return only this structured summary (this is what a coordinator running this as
"count": <number of missing+weak findings>,
"findings": [
{"layer": 1, "topic": "non-goals", "severity": "missing", "note": "one line, specific"},
{"layer": "decision-ask", "topic": "open-question-1", "severity": "weak", "note": "one line, specific — e.g. missing default-if-silence"}
{"layer": "decision-ask", "topic": "open-question-1", "severity": "weak", "note": "one line, specific — e.g. no reason given for why it needs deciding"}
]
}
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Governing standard for the main body: Dieter Rams' "as little design as possible

### What to flag in the MAIN BODY

- **Buried decision/ask** — the thing the reader must decide is not in the first third of the doc, or is stated as narrative rather than named as a decision (compare to the "Decision requested" pattern: numbered asks, one owner, one default-if-silent, each per row)
- **Buried decision/ask** — the thing the reader must decide is not in the first third of the doc, or is stated as narrative rather than named as a decision (compare to the "Decision requested" pattern: numbered asks, each a short section that says why it needs deciding, what we recommend, and what happens if nobody objects; not a wide table)
- **Filler and hedge padding** — "very", "basically", "in order to", "it should be noted that", "due to the fact that" — cut-and-replace, not a style nit
- **Show-my-work** — investigation narrative left in the main body where a conclusion would do. (Exception: if the doc's own convention — e.g. an evidence/appendix split — already routes this to an appendix, that's correct and should NOT be flagged again.)
- **Unquantified risk language** — "significant risk", "should be fine" without a number, a measured event, or a link backing it. Ties to CLAUDE.md's "Evidence and Claims": a claim without a source the reader can check is the same defect whether it's a code comment or a design doc.
Expand Down
13 changes: 10 additions & 3 deletions .claude/skills/gh-signal-inbox/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,16 @@ If it fails: `systemctl --user status gh-signal-inbox` (unit at
`~/.config/systemd/user/gh-signal-inbox.service`; start with
`systemctl --user start gh-signal-inbox`). Do not edit the token file.

Events only arrive if the `gh-signal-bridge` webhook feed (or `/v1/ingest`) is
running for that repo. A quiet inbox with no bridge is not "nothing happened";
if you need certainty, check the PR directly with `gh pr view`.
Events arrive from two sources: the `gh-signal-bridge` webhook feed (or `/v1/ingest`)
and the inbox's built-in polling fallback, which is on by default and only polls
while a PR is subscribed (about every 15-30s while a `wait` is running, every
5 min otherwise). Check polling with `gh-signal inbox health` and read
`ingress.poll.status`: `active` or `idle` is healthy; `disabled`, `unavailable`
or `rate_limited` has a `reason` (for example no `[hosts.*]` token, or a 1Password
read failure). `wait` also prints a stderr warning when polling is disabled or
unavailable. Exit 2 means the server was reachable and nothing was pending, so
the PR was quiet; that is only trustworthy when polling is healthy or webhooks
reach the inbox. If you need certainty, check the PR directly with `gh pr view`.

## Workflow

Expand Down
1 change: 1 addition & 0 deletions .claude/skills/writing/CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ skill's own instructions — it's the index of *why* a rule exists and *where* t

| Check | Catches | Evidence / citation | Implemented in |
|---|---|---|---|
| Long prose in table cells | A table whose cells hold sentences or paragraphs (decision tables with rationale, owner, trigger and default per row): hard to read, hard to edit in Markdown, and gets poor reviewer feedback | [Google developer docs style guide, Tables](https://developers.google.com/style/tables): tables are for data with three or more related pieces per item, and only for two-dimensional data; [Google Markdown style guide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md): keep cells short, and "rambling prose in cells" is a sign a table is the wrong format; [Open Group Technical Publications Style Guide, 3.24](https://pubs.opengroup.org/handbooks/technical-publications-styleguide/chap3.html): use headings when list items run to several paragraphs. Replacement: one short headed section per decision (why, recommendation, default), grouped by what it blocks. Search-summary evidence, pages not all opened | `design-doc-review:outline` (Decision Ask), `design-doc-review:readability` |
| Overlong, unbroken paragraph | A paragraph carrying more than one idea, hurting scannability | [Google Developer Documentation Style Guide, Paragraph structure](https://developers.google.com/style/paragraph-structure): >5-6 sentences signals multiple ideas — already this repo's cited house style per `CLAUDE.md`'s Writing Style section | `design-doc-review:readability` |
| Wall of text (soft signal) | A block of prose with no internal line breaks — the default shape LLMs fall back to in short-form writing | [`avoid-ai-writing`](https://github.com/conorbronsdon/avoid-ai-writing) project notes; mechanism traced to attention allocation on separator tokens, [SepLLM, arXiv:2412.12094](https://arxiv.org/abs/2412.12094). **Caveat, from that same project**: a standalone detector was reverted because dense human paragraphs share the same shape — register/redundant-context matter more than shape alone, so this is corroborating evidence, never a sole trigger | `writing-humanize` (Structural Signature Scan table + `references/research-notes.md`) |
| Unsourced claim / missing citation | A factual statement with no link, file:line, or command output backing it | `CLAUDE.md`'s own "Evidence and Claims" section (this org's already-agreed standard — this check mechanizes it, doesn't invent a new one); general fact-checking practice ("how do you know this?" test, verify-before-publish) is standard across editorial fact-checking guides | `design-doc-review:evidence` (new) |
Expand Down
4 changes: 3 additions & 1 deletion bootstrap-pyinfra/_test_runner.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,10 @@
underscore keeps it out of both globs).
"""

from typing import Any

def run_tests(namespace: dict) -> None:

def run_tests(namespace: dict[str, Any]) -> None:
tests = [value for key, value in namespace.items() if key.startswith("test_")]
for test in tests:
test()
Expand Down
5 changes: 3 additions & 2 deletions bootstrap-pyinfra/scoped_devbox_setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@
Not part of main.py — deliberately skips nix/secrets/sudo-mfa/fbg/claude/
ai_tools/pi/shell/asdf/fonts/github, which were not asked for here.
"""
from deploys.homebrew import homebrew

from deploys.dotfiles import dotfiles
from deploys.overlays import overlays
from deploys.homebrew import homebrew
from deploys.llm_sync import llm_sync
from deploys.overlays import overlays

homebrew()
dotfiles()
Expand Down
Loading