@tplog/hasapi 0.1.0

package/hasapi-skills/hasapi-review/pr-review-guide.md

@@ -0,0 +1,163 @@
+# PR Review Guide — Mode 1
+
+**Purpose:** Analyze a code diff or specific files for decay risks that are directly visible
+in the changed code. Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.
+
+---
+
+## Before You Start
+
+**Auto-generated files:** If the diff contains generated files (protobuf stubs, OpenAPI clients,
+ORM migrations, lock files, minified bundles), skip those files entirely. Generated code reflects
+tool choices, not developer decisions. Note in the report which files were skipped and why.
+
+**Scope calibration:** Adjust analysis depth based on PR size before starting.
+
+| PR Size | Approach |
+|---------|----------|
+| < 50 lines | Focus on Steps 1–3 only; run Step 6a only if imports changed; run Step 6b if any class, method, or variable was renamed or introduced |
+| 50–300 lines | Full process, all steps |
+| > 300 lines | Full process; note in the Scope line that review is sampled — cover the highest-risk areas rather than every file |
+
+For PRs > 500 lines: flag in the Summary that a PR this size is itself a Change Propagation signal. A change that cannot be reviewed in one pass suggests tangled responsibilities.
+
+---
+
+## Analysis Process
+
+Work through these seven steps in order. Do not skip steps.
+
+### Step 1: Understand the scope
+
+Read the diff or files and answer:
+- What is the stated purpose of this change?
+- Which files were modified?
+- Flag immediately if the PR changes more than 10 unrelated files — that itself is a
+  🟡 Warning: Change Propagation (a PR that touches many unrelated things is a sign
+  that responsibilities are tangled).
+
+### Step 2: Scan for Change Propagation
+
+*Scan this first — it is the most visible risk in a diff.*
+
+Look for:
+- Does this change touch files in modules that have no conceptual connection to the stated purpose?
+- Does any modified class change for more than one business reason in this diff?
+- Does any method use more data from another class than from its own?
+
+If the diff shows no cross-module changes beyond what the feature requires → skip, no finding.
+
+### Step 3: Scan for Cognitive Overload
+
+Look for:
+- Are any new or modified functions longer than 20 lines?
+- Is there nesting deeper than 3 levels in new or modified code?
+- Are there more than 4 parameters in any new function signature?
+- Are there magic numbers or unexplained constants in new code?
+- Do new variable or function names require reading the implementation to understand?
+- Are there train-wreck chains (3+ method calls chained)?
+
+### Step 4: Scan for Knowledge Duplication
+
+Look for:
+- Does this change introduce logic that already exists elsewhere in the codebase?
+- Does this change introduce a new name for a concept that already has a name?
+- Does this change add a class to a hierarchy that has a parallel in another module?
+
+### Step 5: Scan for Accidental Complexity
+
+Look for:
+- Does this change add an abstraction with only one concrete use?
+- Does this change add a class that only wraps another class or delegates everything?
+- Does this change add configuration options or extension points that serve no current requirement?
+
+### Step 6a: Scan for Dependency Disorder
+
+- Do any new imports create a dependency from a high-level module to a low-level one?
+  (e.g., domain service now imports a database driver or HTTP client)
+- Do any new imports introduce a cycle between modules?
+- Does any new interface force callers to depend on methods they do not use?
+
+If no new imports and no structural changes → skip, no finding.
+
+### Step 6b: Scan for Domain Model Distortion
+
+- Do new class or variable names match the language the business uses for the same concept?
+- Does any new class hold only data with no behavior (pure data bag), where behavior was expected?
+- Does any new method put logic that belongs to the domain in a service or utility layer?
+
+---
+
+## Severity Calibration
+
+Apply the Iron Law format from `../_shared/common.md`. Each risk in `../_shared/decay-risks.md` has its own Severity
+Guide with numeric thresholds — use those as the primary reference. When a finding sits
+on the boundary between two tiers, use this as a tiebreaker:
+- 🔴 Critical — actively breaking velocity or creating production risk *today*
+- 🟡 Warning — will if left unaddressed through the next few features
+- 🟢 Suggestion — worth fixing when nearby, not urgent
+
+When multiple findings exist, list Critical items first. If there are more than 5 findings,
+add a one-line "Recommended fix order" at the end of the Findings section.
+
+---
+
+## Step 7: Quick Test Check
+
+*Run this last. Three signals only — this is not a full Mode 4 review.*
+
+If the diff contains only generated files, configuration, or documentation with no
+production logic changes → skip Step 7 entirely.
+
+**Signal 1: Do tests exist for the changed behavior?**
+
+- Does the diff modify production code?
+- Are corresponding test file changes included in the diff?
+- If new public behavior was added with no new tests:
+  → 🟡 Warning: Coverage Illusion — new behavior is untested
+  → Source: Feathers — Working Effectively with Legacy Code, Ch. 1
+- If the change is a pure refactor and existing tests cover the behavior → no finding.
+
+**Signal 2: Quick Mock Abuse sniff**
+
+Only check if the diff includes test file changes.
+
+- Is mock setup code in new/modified tests obviously longer than the test logic?
+- Are the primary assertions `expect(mock).toHaveBeenCalledWith(...)` with no behavior verification?
+- Does the diff add any methods to production classes that are only called from test files?
+
+If any of these are true:
+  → 🟡 Warning: Mock Abuse — test complexity exceeds behavior complexity
+  → Source: Osherove — The Art of Unit Testing, mock usage guidelines
+
+**Signal 3: Quick Test Obscurity sniff**
+
+Only check if the diff includes test file changes.
+
+- Do new test names express scenario and expected outcome?
+  (Pattern: `methodName_scenario_expectedResult` or equivalent)
+- Are there new tests with multiple assertions and no message strings on any of them?
+
+If test names are vague or assertions lack messages:
+  → 🟢 Suggestion: Test Obscurity — test intent is unclear from the test name or assertions
+  → Source: Meszaros — xUnit Test Patterns, Assertion Roulette (p.224)
+
+**Output rule:**
+
+If all three signals are clean → write no Test findings. Proceed directly to the report.
+
+If findings exist → add them to the Findings section using the standard Iron Law format.
+Label the risk as the test decay risk name (e.g., "Coverage Illusion", "Mock Abuse",
+"Test Obscurity").
+
+> **Note:** Step 7 is a fast check, not a full test audit. When systemic test problems
+> are found, note in the Summary: "Consider running `/brooks-lint:brooks-test` for a
+> complete test quality diagnosis."
+
+---
+
+## Output
+
+Use the standard Report Template from `../_shared/common.md`.
+Mode: PR Review
+Scope: list the files reviewed (excluding skipped generated files).

package/hasapi-skills/hasapi-setup/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: hasapi-setup
+description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
+disable-model-invocation: true
+---
+
+# Setup Matt Pocock's Skills
+
+Scaffold the per-repo configuration that the engineering skills assume:
+
+- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Triage labels** — the strings used for the five canonical triage roles
+- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
+- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/` — does this skill's prior output already exist?
+- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+
+Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
+
+- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
+- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+**Section B — Triage label vocabulary.**
+
+> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+
+The five canonical roles:
+
+- `needs-triage` — maintainer needs to evaluate
+- `needs-info` — waiting on reporter
+- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
+- `ready-for-human` — needs human implementation
+- `wontfix` — will not be actioned
+
+Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
+
+**Section C — Domain docs.**
+
+> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
+
+Confirm the layout:
+
+- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
+- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `CLAUDE.md` exists, edit it.
+- Else if `AGENTS.md` exists, edit it.
+- If neither exists, ask the user which one to create — don't pick for them.
+
+Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Then write the three docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](./triage-labels.md) — label mapping
+- [domain.md](./domain.md) — domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/hasapi-skills/hasapi-setup/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/hasapi-skills/hasapi-setup/issue-tracker-github.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/hasapi-skills/hasapi-setup/issue-tracker-gitlab.md

@@ -0,0 +1,23 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.

package/hasapi-skills/hasapi-setup/issue-tracker-local.md

@@ -0,0 +1,19 @@
+# Issue tracker: Local Markdown
+
+Issues and PRDs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The PRD is `.scratch/<feature-slug>/PRD.md`
+- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.

package/hasapi-skills/hasapi-setup/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/hasapi-skills/hasapi-sweep/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: hasapi-sweep
+description: >
+  Full-sweep mode: runs a unified analysis across all quality dimensions — code decay,
+  architecture, tech debt, and test quality — then applies fixes directly to the
+  codebase. Safe changes are auto-applied; risky changes are confirmed before
+  execution. Drawing on twelve classic engineering books.
+  Triggers when: user wants to "fix everything", "sweep the codebase", "auto-fix all
+  issues", "run all checks and fix them", "clean up the whole project", or asks for
+  a single command that both diagnoses and remediates quality problems.
+  Do NOT trigger for: read-only audits or health reports where the user only wants
+  findings without code changes; single-dimension reviews (use the focused skill
+  instead: brooks-review / brooks-audit / brooks-debt / brooks-test); server health
+  checks, HTTP /health endpoints, Kubernetes probes, or application uptime.
+---
+
+# Brooks-Lint — Full Sweep & Auto-Fix
+
+## Setup
+
+1. Read `../_shared/common.md` for the Iron Law, Project Config, Report Template, and Health Score rules
+2. Read `../_shared/source-coverage.md` for book-level coverage, exceptions, and tradeoffs
+3. Read `../_shared/decay-risks.md` for production risk symptom definitions
+4. Read `../_shared/test-decay-risks.md` for test risk symptom definitions
+5. Read `sweep-guide.md` in this directory for the unified scan and fix process
+
+## Process
+
+**If the user has not specified a project or directory:** apply Auto Scope Detection
+from `../_shared/common.md` to determine the review scope before proceeding.
+
+1. Show pre-flight consent notice and wait for the user's one-time approval (Step 0 of the guide)
+2. Enumerate scope and initialize the `unresolvable` / `non_critical_rounds` / `fix_log` state (Step 1 of the guide)
+3. Run the four dimensions in sequence — review, test, debt, audit — each scanning, classifying, applying Safe + Extended-Safe fixes, and verifying via the project test command (Steps 2–5 of the guide)
+4. Iterate: re-scan modified files + same-module + static consumers; converge on a clean round, retire 3-retry failures to the `unresolvable` set, cap non-critical rounds at 3 (Step 6 of the guide)
+5. Aggregate residual and unresolvable items and output the Full Sweep Report (Steps 7–8 of the guide)
+
+**Mode line in report:** `Full Sweep`