@tplog/hasapi 0.1.0

package/hasapi-skills/hasapi-debt/debt-guide.md

@@ -0,0 +1,125 @@
+# Tech Debt Assessment Guide — Mode 3
+
+**Purpose:** Identify, classify, and prioritize technical debt across the entire codebase.
+Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.
+
+---
+
+## Evidence Gathering
+
+If you have insufficient evidence to assess the codebase, ask the user ONE question —
+choose the single question most relevant to what you already know:
+
+1. "Which part of the codebase takes the longest to modify for a typical feature?"
+2. "Which module do developers avoid touching, and why?"
+3. "Which parts of the system have the fewest tests and the most bugs?"
+4. "Is there a module that only one person fully understands?"
+
+After one answer, proceed. Do not ask more than one question.
+If the user declines or says they don't know, proceed with available evidence and note
+which areas could not be assessed.
+
+---
+
+## Analysis Process
+
+Work through these four steps in order.
+
+### Step 1: Full Decay Risk Scan
+
+Scan for all six decay risks across the entire codebase. List every finding before scoring
+any of them. This prevents anchoring on early findings and missing systemic patterns.
+
+For each risk, look for:
+
+**Cognitive Overload:** Are there widespread naming problems, deeply nested logic, or
+excessively long functions spread across many modules?
+
+**Change Propagation:** Which modules cause the most ripple effects when changed?
+Are there modules that everyone must modify when adding a new feature?
+
+**Knowledge Duplication:** How many times is the same concept implemented independently?
+Is the domain vocabulary consistent across the codebase?
+
+**Accidental Complexity:** Are there architectural layers or abstractions that add no value?
+Is the infrastructure overhead proportional to the problem being solved?
+
+**Dependency Disorder:** Are there dependency cycles? Does domain logic depend on infrastructure?
+Are there modules with no clear layering position?
+
+**Domain Model Distortion:** Is business logic in the right layer?
+Do code names match business names? Are domain objects anemic?
+
+### Step 2: Score Each Finding with Pain × Spread
+
+After listing all findings, score each one:
+
+**Pain score (1–3):** How much does this slow down development today?
+- 3: Developers actively avoid touching this area; it causes bugs on most changes
+  *(e.g., "nobody wants to touch the billing module because it always breaks something")*
+- 2: This area is noticeably slower to work in than the rest of the codebase
+  *(e.g., "adding a field takes 2–3x longer here than elsewhere")*
+- 1: This is a quality issue but not currently causing active pain
+  *(e.g., "inconsistent naming, but we always know what we mean")*
+
+**Spread score (1–3):** How many files, modules, or developers does this affect?
+- 3: Affects 5+ modules or all developers on the team
+  *(e.g., "every new feature touches the God class in core/")*
+- 2: Affects 2–4 modules or a subset of the team
+  *(e.g., "the auth and notification modules are tightly coupled")*
+- 1: Isolated to one module or one developer's area
+  *(e.g., "legacy parser that only one person maintains")*
+
+**Priority = Pain × Spread** (max 9)
+
+| Priority | Classification | Action |
+|----------|---------------|--------|
+| 7–9 | Critical debt | Address in next sprint |
+| 4–6 | Scheduled debt | Plan within quarter |
+| 1–3 | Monitored debt | Log and watch |
+
+### Step 3: Classify Debt Intent
+
+After scoring, classify each finding as intentional or accidental:
+
+**Intentional debt** — a conscious shortcut taken to meet a deadline, with the expectation
+of paying it back. The team knows about it. It may be legitimate (a strategic prototype,
+a known temporary workaround during a migration).
+
+**Accidental debt** — degradation that accumulated without a deliberate decision: the team
+did not choose it and may not even know it exists. This is the kind Ward Cunningham's
+original definition warned against — not a tactical trade-off, but structural erosion.
+
+Mark each finding with `[intentional]` or `[accidental]` in the Debt Summary Table.
+Intentional debt with no visible payback plan — no linked ticket, no code comment, no
+documented decision — should be treated as accidental for prioritization purposes.
+Focus remediation energy on accidental debt first; intentional debt at least has an owner.
+
+### Step 4: Group by Decay Risk
+
+Report findings grouped by risk type, not by file or module.
+Grouping by risk reveals systemic patterns:
+- "Change Propagation is systemic" → architectural intervention needed
+- "Cognitive Overload is isolated" → localized refactoring sufficient
+
+---
+
+## Output
+
+Use the standard Report Template from `../_shared/common.md`. Mode: Tech Debt Assessment.
+
+After Findings, append a Debt Summary Table:
+
+```
+## Debt Summary
+| Risk | Findings | Avg Priority | Classification | Intent |
+|------|----------|-------------|----------------|--------|
+| Cognitive Overload      | N | X.X | Monitored/Scheduled/Critical | intentional/accidental |
+| Change Propagation      | N | X.X | ... | ... |
+| Knowledge Duplication   | N | X.X | ... | ... |
+| Accidental Complexity   | N | X.X | ... | ... |
+| Dependency Disorder     | N | X.X | ... | ... |
+| Domain Model Distortion | N | X.X | ... | ... |
+
+**Recommended focus:** [risks with highest average priority]
+```

package/hasapi-skills/hasapi-diagnosing-bugs/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: hasapi-diagnosing-bugs
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+---
+
+# Diagnosing Bugs
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/hasapi-skills/hasapi-diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

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

@@ -0,0 +1,10 @@
+---
+name: hasapi-grilling
+description: Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

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

@@ -0,0 +1,16 @@
+---
+name: hasapi-handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

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

@@ -0,0 +1,37 @@
+---
+name: hasapi-health
+description: >
+  Combined codebase health dashboard that scores a project across all four quality
+  dimensions — PR quality, architecture, tech debt, and test quality — in a single
+  pass, drawing on twelve classic engineering books.
+  Triggers when: user wants an overall quality assessment, asks "how healthy is this
+  codebase?", "run all the checks", "give me a big-picture quality report", "I need a
+  health score before the release", "what's the overall state of our code?", or wants
+  to onboard a new team with a quality overview.
+  Do NOT trigger for: server health checks, HTTP health endpoints, Kubernetes
+  liveness/readiness probes, database health, or application uptime. Also do not
+  trigger when the user specifically requests only one dimension — use the
+  corresponding focused skill instead (brooks-review / brooks-audit /
+  brooks-debt / brooks-test).
+---
+
+# Brooks-Lint — Health Dashboard
+
+## 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 `health-guide.md` in this directory for the dashboard orchestration 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. Run abbreviated scans across all four dimensions (Step 1 of the guide)
+2. Compute per-dimension and composite Health Scores with weighting (Step 2 of the guide)
+3. Output the Health Dashboard using the dashboard report template (Step 3 of the guide)
+
+**Mode line in report:** `Health Dashboard`

package/hasapi-skills/hasapi-health/health-guide.md

@@ -0,0 +1,89 @@
+# Health Dashboard Guide — Mode 5
+
+**Purpose:** Produce a cross-dimensional health dashboard for the codebase.
+Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.
+
+---
+
+## Analysis Process
+
+### Step 1: Run Lightweight Scan Across Four Dimensions
+
+For each dimension, run an abbreviated scan using the decay-risks definitions
+from `_shared/`. Do NOT read the individual mode guide files — use the abbreviated
+checklists below. Cap each dimension at 3 findings; for Debt: cap at 2 per risk code and 3 across all risk codes.
+
+**PR dimension (if changes exist):**
+- Apply Auto Scope Detection (common.md)
+- Scan for R2 (Change Propagation) and R1 (Cognitive Overload) in the diff
+
+**Architecture dimension:**
+- Gather codebase context: read top-level structure, entry points, import statements
+- Draw a Mermaid dependency graph (follow standard graph rules from common.md)
+- Scan for R5 (Dependency Disorder): circular deps, upward flows, fan-out > 5
+- INCLUDE the Mermaid graph in output
+
+**Debt dimension:**
+- Scan for all six decay risks (R1-R6) across the codebase
+- Skip Pain × Spread scoring (use severity tier only)
+
+**Test dimension:**
+- Build the Test Suite Map (unit/integration/E2E counts)
+- Scan for T1 (Test Obscurity) and T2 (Test Brittleness) in test files
+
+### Step 2: Compute Dashboard Scores
+
+Each dimension gets its own Health Score (base 100, same deduction rules from common.md).
+Composite score = weighted average of dimension scores:
+
+| Dimension | Weight | Rationale |
+|-----------|--------|-----------|
+| PR (code quality) | 0.25 | Only applies if changes exist; skip if no diff |
+| Architecture | 0.30 | Structural issues have highest blast radius |
+| Debt | 0.25 | Systemic but slower-moving |
+| Test | 0.20 | Supporting signal |
+
+If PR dimension is skipped (no changes), redistribute its 0.25 weight proportionally
+across the remaining three dimensions by dividing each remaining weight by
+(1 − 0.25) = 0.75. Compute redistribution dynamically — do not hardcode the values.
+
+**Redistributed weights (PR skipped):**
+
+| Dimension | Base Weight | Redistributed Weight |
+|-----------|------------|---------------------|
+| Architecture | 0.30 | 0.30 / 0.75 = 0.40 |
+| Debt | 0.25 | 0.25 / 0.75 = 0.33 |
+| Test | 0.20 | 0.20 / 0.75 = 0.27 |
+
+### Step 3: Output Dashboard
+
+Use the dashboard report template below instead of the standard common.md template.
+
+---
+
+## Dashboard Report Template
+
+````markdown
+# Brooks-Lint Health Dashboard
+
+**Mode:** Health Dashboard
+**Scope:** [project name or directory]
+**Composite Score:** XX/100
+
+| Dimension | Score | Top Finding |
+|-----------|-------|------------|
+| Code Quality | XX/100 | [one-line summary or "Clean"] |
+| Architecture | XX/100 | [one-line summary or "Clean"] |
+| Tech Debt | XX/100 | [one-line summary or "Clean"] |
+| Test Quality | XX/100 | [one-line summary or "Clean"] |
+
+## Module Dependency Graph
+[Mermaid graph from architecture scan]
+
+## Top Findings (max 5 across all dimensions)
+[Standard Iron Law format, sorted by severity]
+
+## Recommendation
+[One paragraph: what to fix first, which dimension needs the most attention,
+ suggest running the full individual skill for the worst dimension]
+````

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

@@ -0,0 +1,15 @@
+---
+name: hasapi-implement
+description: "Implement a piece of work based on a PRD or set of issues."
+disable-model-invocation: true
+---
+
+Implement the work described by the user in the PRD or issues.
+
+Use /skill:hasapi-tdd where possible, at pre-agreed seams.
+
+Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+
+Once done, use /skill:hasapi-review to review the work.
+
+Commit your work to the current branch.

package/hasapi-skills/hasapi-resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: hasapi-resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

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

@@ -0,0 +1,37 @@
+---
+name: hasapi-review
+description: >
+  PR code review that surfaces decay risks, design smells, and maintainability
+  issues with concrete Symptom → Source → Consequence → Remedy findings, drawing
+  on twelve classic engineering books.
+  Triggers when: user asks to review code, check a PR, shares a diff or pastes
+  code asking "does this look right?" / "any issues here?" / "ready to merge?",
+  or asks for feedback on a function, class, or file.
+  Also triggers when user mentions: code smells / refactoring / clean architecture /
+  DDD / domain-driven design / SOLID principles / Hyrum's Law / deep modules /
+  tactical programming / conceptual integrity / Brooks's Law / Mythical Man-Month /
+  second system effect.
+  Do NOT trigger for: questions about how to write code from scratch, language syntax
+  questions, or framework/tool questions where no existing code is shared.
+---
+
+# Brooks-Lint — PR Review
+
+## 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 symptom definitions and source attributions
+4. Read `pr-review-guide.md` in this directory for the analysis process
+
+## Process
+
+**If the user has not specified files or pasted code:** apply Auto Scope Detection
+from `../_shared/common.md` to determine the review scope before proceeding.
+
+1. Understand the review scope, then scan for each decay risk in the order specified (Steps 1–6 of the guide)
+2. Run the Quick Test Check (Step 7 of the guide) — skip for docs-only or non-production changes
+3. Apply the Iron Law to every finding
+4. Output using the Report Template from common.md
+
+**Mode line in report:** `PR Review`