From afc868a1e1b74647b65c51f0c1114d0bb898161c Mon Sep 17 00:00:00 2001 From: Tyler Stapler Date: Sun, 8 Nov 2026 12:22:43 -0800 Subject: [PATCH] chore: commit local skill and bootstrap-pyinfra edits Co-Authored-By: Claude Sonnet 5.5 --- .claude/skills/code-hotspot-analysis/SKILL.md | 27 ++++++++++++++----- .../design-doc-review/skills/outline/SKILL.md | 17 ++++++------ .../skills/readability/SKILL.md | 2 +- .claude/skills/gh-signal-inbox/SKILL.md | 13 ++++++--- .claude/skills/writing/CHECKLIST.md | 1 + bootstrap-pyinfra/_test_runner.py | 4 ++- bootstrap-pyinfra/scoped_devbox_setup.py | 5 ++-- 7 files changed, 48 insertions(+), 21 deletions(-) diff --git a/.claude/skills/code-hotspot-analysis/SKILL.md b/.claude/skills/code-hotspot-analysis/SKILL.md index c71606aa..557cb16d 100644 --- a/.claude/skills/code-hotspot-analysis/SKILL.md +++ b/.claude/skills/code-hotspot-analysis/SKILL.md @@ -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-.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 | |---|---|---|---| @@ -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: "::."` 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/-kib origin/main`, write `{}` to +`/tmp/-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): diff --git a/.claude/skills/design-doc-review/skills/outline/SKILL.md b/.claude/skills/design-doc-review/skills/outline/SKILL.md index 8b1e5edc..95e1bf4c 100644 --- a/.claude/skills/design-doc-review/skills/outline/SKILL.md +++ b/.claude/skills/design-doc-review/skills/outline/SKILL.md @@ -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 @@ -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 @@ -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) @@ -82,7 +83,7 @@ Return only this structured summary (this is what a coordinator running this as "count": , "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"} ] } ``` diff --git a/.claude/skills/design-doc-review/skills/readability/SKILL.md b/.claude/skills/design-doc-review/skills/readability/SKILL.md index 046438ad..f7f8aa9a 100644 --- a/.claude/skills/design-doc-review/skills/readability/SKILL.md +++ b/.claude/skills/design-doc-review/skills/readability/SKILL.md @@ -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. diff --git a/.claude/skills/gh-signal-inbox/SKILL.md b/.claude/skills/gh-signal-inbox/SKILL.md index 8e6dab85..a76d6c65 100644 --- a/.claude/skills/gh-signal-inbox/SKILL.md +++ b/.claude/skills/gh-signal-inbox/SKILL.md @@ -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 diff --git a/.claude/skills/writing/CHECKLIST.md b/.claude/skills/writing/CHECKLIST.md index 3e1fd872..69cd858c 100644 --- a/.claude/skills/writing/CHECKLIST.md +++ b/.claude/skills/writing/CHECKLIST.md @@ -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) | diff --git a/bootstrap-pyinfra/_test_runner.py b/bootstrap-pyinfra/_test_runner.py index 3ca20046..6b0e1406 100644 --- a/bootstrap-pyinfra/_test_runner.py +++ b/bootstrap-pyinfra/_test_runner.py @@ -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() diff --git a/bootstrap-pyinfra/scoped_devbox_setup.py b/bootstrap-pyinfra/scoped_devbox_setup.py index dd5f2474..00962d78 100644 --- a/bootstrap-pyinfra/scoped_devbox_setup.py +++ b/bootstrap-pyinfra/scoped_devbox_setup.py @@ -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()