@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-maintainability-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: hr-maintainability-review
+description: "Review a diff or an entire codebase for maintainability and structure, preserving behavior. Use when explicitly requested for a strict, deep or harsh maintainability review, or a whole-repository over-engineering or bloat audit. Report-only; correctness, UI quality, test coverage and measured performance need separate assessments."
+disable-model-invocation: true
+---
+
+# Maintainability review
+
+A demanding read of the requested code, asking a single question: is this
+the simplest shape the code could take while doing exactly what it does now?
+Correctness is out of scope. For a routine review against repository
+standards, use `hr-code-review`; for hunting a bug, use `hr-diagnosing-bugs`. This
+review changes no code; it reports findings and a verdict.
+
+## Choose the scope
+
+Use the user's requested scope: a diff, a subsystem or the entire repository.
+Record the revision and whether working-tree and untracked files are included.
+For a whole-codebase review, recent changes may inform priority but never narrow
+coverage to touched files. If the request names no scope, use the current
+branch's changes against the repository's default branch.
+
+### Diff review
+
+1. Find the branch's base with the repository's default branch, not a guessed
+   name, and read the full diff against it.
+2. Read every touched file whole, not only the hunks. Structure problems sit in
+   how new lines fit the old ones.
+3. For each new function, type, flag or module, read its callers and look for
+   an existing helper, module or pattern that already does the job.
+4. Note each file's length before and after the change.
+
+Done when you can explain, for every touched file, what it owned before the
+change and what it owns now.
+
+### Whole-repository or subsystem review
+
+1. Inventory the in-scope packages, modules, entry points and shared code.
+   Record generated and vendor code, exclusions and inaccessible areas.
+2. Review each area and trace its consumers and cross-module boundaries.
+   Read candidate files whole; inspect callers, tests and configuration before
+   declaring a layer, branch or helper unnecessary. Search dynamic and string
+   references too when proposing deletion.
+3. Record each area's assessment, supporting files and remaining gaps. Mark
+   an area assessed only after inspecting its implementation and relevant
+   consumers; inventory or file counts alone do not establish coverage.
+
+Done when every inventoried area has an assessment or an explicit note that it was
+not reviewed. Report gaps rather than claiming a complete audit from a sample.
+
+## What to challenge
+
+- **Special cases in shared flows.** An `if` for one caller, one tenant or one
+  feature inside a path everyone uses. Ask whether the case belongs at the
+  caller, in data, or in a separate path.
+- **Files past what a reader can hold.** When a file grows large enough that
+  nobody can keep its whole shape in mind, ask whether it should be split
+  before this change lands, and where the seam is.
+- **Pass-through layers.** Wrappers, adapters and services that forward calls
+  with renamed arguments. Indirection must buy clarity, isolation or a real
+  second implementation. Test a suspect module by imagining it deleted: if its
+  complexity would spread into every caller, it is earning its keep; propose
+  removal only when callers could use the underlying behavior directly without
+  duplicating or redistributing that complexity.
+- **Generic machinery over a simple shape.** Registries, plugin systems,
+  builders or configurable pipelines where the data is a fixed list or a plain
+  record.
+- **Loose types hiding an invariant.** Casts, `any`, broad unions and optional
+  fields that cover a rule nobody wrote down. Often the fix is two types, or a
+  required field set at construction.
+- **Logic in the wrong home.** Code that reaches into another module's
+  internals, belongs beside the data it reads, or repeats a helper that already
+  exists.
+- **Forced ordering.** Independent steps chained one after another, so a slow
+  or failing step blocks unrelated ones.
+- **Half-applied updates.** A multi-step write that leaves state inconsistent
+  if it stops partway. Look for a single transaction, a write-then-swap, or a
+  shape where partial state cannot exist.
+- **Modes and flags.** A boolean parameter or mode switch that splits one
+  function into two behaviors sharing a name.
+- **Leftover scaffolding.** Stubs and placeholders still on a live path, fixed
+  sample data where real data should flow, functions that report success
+  without doing their work, handlers that silently do nothing, "temporary"
+  branches that shipped, and comments describing a refactor long finished.
+  Propose deleting what no consumer needs. When a consumer depends on one, the
+  real behavior is missing: report it under **Other assessments** as a
+  correctness concern, without guessing at the contract the code never showed.
+
+## Look for code that disappears
+
+The most valuable finding removes moving parts outright: a branch, mode,
+layer or helper that stops being needed once the change is framed differently
+or leans on what the architecture already provides. Examples of the move:
+
+- the new flag goes away if the caller passes the value it already has;
+- the special case goes away if the shared type carries the field;
+- the wrapper goes away if callers use the underlying API directly;
+- the retry layer goes away if the operation is made idempotent.
+
+Aim past a tidier copy of the same design. When a different framing would
+make a whole branch, mode or layer unnecessary, argue for that framing
+rather than for local cleanup.
+
+Propose such a restructure only when you can name the files, the parts that
+go, and what replaces them. A vague "this could be simpler" is not a finding.
+Moving code between files without removing anything is weaker than deleting
+it; renaming is not a remedy for a structural problem.
+
+## Filter
+
+Keep a finding only when all of these hold:
+
+- you can describe the restructure concretely;
+- behavior stays the same after it, including errors and edge cases;
+- it removes complexity a future maintainer would pay for.
+
+Order findings by structural impact, largest first. Prefer three solid
+findings to ten guesses. Drop cosmetic notes (naming, formatting, comment
+wording) whenever any structural finding exists. If the change has no
+structural problem, say so in one sentence; do not invent one to fill the
+report.
+
+## Write each finding
+
+For each finding, give in order:
+
+1. **Where**: file and line range, or the functions involved.
+2. **Problem**: what makes this shape costly to read or change, in one or two
+   sentences.
+3. **Restructure**: the concrete change, with a short sketch when prose is
+   ambiguous.
+4. **What goes away**: the branches, types, files or lines removed.
+5. **Behavior check**: why behavior is unchanged, and which tests would show
+   it.
+
+## Verdict
+
+Include the scope and coverage limits with the verdict. Whole-repository and
+subsystem reviews use **Priority fixes**, **Optional** and **Overall**: rank current
+maintenance costs and state what was assessed, rather than judging whether
+existing code is ready to merge. For a diff, use these three parts:
+
+- **Before merge**: findings whose shape will be expensive to undo once other
+  code depends on it, each with its restructure.
+- **Optional**: improvements worth doing now or later, each with its
+  restructure.
+- **Overall**: one line stating whether the structure is ready to merge.
+
+If nothing must change, the "Before merge" list says "none".
+
+For diff reviews, working behavior alone does not make the structure ready. Each of these
+goes under "Before merge" unless the author gives a clear reason to keep it:
+
+- a visible restructure that would delete much of the change's incidental
+  complexity, left untaken;
+- new special-case branches that tangle a shared flow;
+- feature checks spread across shared code to solve a local problem;
+- a new wrapper, cast or loosely typed contract that adds indirection
+  without paying for it;
+- a near-copy of an existing helper, or logic placed outside the module
+  that owns the concept.
+
+## Other assessments
+
+For a request combining several kinds of review, account for each separately:
+
+- **Correctness:** `hr-code-review` assesses a diff against requirements;
+  `hr-diagnosing-bugs` investigates a concrete suspected failure. Neither a
+  structural verdict nor a diff review establishes whole-codebase correctness.
+- **UI:** use the available `hr-better-*` skills for the requested layout,
+  typography, colors, accessibility or interface copy; `hr-stock-ui-audit`
+  targets template-default styling.
+- **Tests:** `hr-test-audit` assesses test value and duplication. Record test
+  execution and coverage separately; do not infer coverage from test count.
+- **Performance:** `hr-benchmarking` measures an authorized workload; inspect
+  build artifacts when bundle size is requested. Label unmeasured claims.
+- **Agent guidance:** `hr-agent-guidance-audit` checks rules, skills and their
+  references for duplication, contradictions and stale instructions.
+
+Use these workflows only for the requested dimensions and within their
+invocation policies. Report unavailable or unassessed dimensions explicitly.
+
+## Tone
+
+Direct and serious. Name the problem plainly and explain the cost. Never mock
+the author, and never soften a required change into a suggestion.

package/skills/hr-maintainability-review/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Maintainability review"
+  short_description: "Strict maintainability or bloat review of a diff or codebase"
+policy:
+  allow_implicit_invocation: false

package/skills/hr-manual-qa/NOTICE.md

@@ -0,0 +1,36 @@
+# Source notices
+
+This notice accompanies the hr-manual-qa bundle when copied on its own.
+
+## Jeanno/jeanno-skills (ideas)
+
+Source: https://github.com/Jeanno/jeanno-skills (compared at revision `db4e8fd66197ece38d622ca8b527dbe821843df2`)
+
+- `skills/hr-manual-qa/SKILL.md`: independently written instructions informed by
+  the reproducible-checklist idea in `skills/qa-checklist/SKILL.md`.
+
+No source text is copied; these instructions are independently written.
+
+## house-rules and MIT permission notice
+
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-manual-qa/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: hr-manual-qa
+description: "Make a reproducible manual verification checklist when the user requests manual QA, or a change needs a device, access or human judgment the agent lacks. Exclude checks the agent can automate or perform itself."
+---
+
+# Manual QA
+
+Turn changed behavior and credible regression risks into observations the user
+can reproduce. Follow the project's verification and domain safeguards.
+
+1. Identify the changed flow and its expected behavior from the request, diff
+   and existing requirements. Name missing information that affects a check.
+2. Reuse verification results already obtained and run remaining relevant
+   agent-accessible checks within current authorization. Report each check's
+   command or context and actual result: passed, failed, blocked or not run.
+   Keep failed checks visible; a manual checklist does not establish a pass.
+3. Select the observations that still need the user's device, access or
+   judgment. Keep agent-runnable checks with the agent. When no manual
+   observation is needed, say so instead of inventing a checklist.
+4. Ground regression checks in the changed flow and supported surfaces. Use
+   available impact findings and UI guidance. When a consequential risk needs
+   investigation and `hr-code-review` is available, use it for that risk;
+   otherwise name the uncertainty. A checklist does not require a full impact
+   assessment.
+5. Present agent results first. When a manual observation remains, include a
+   quick smoke check of the changed flow and any further required user checks.
+   When none remains, do not request a user smoke check. Each manual check names:
+   - **Setup**: device, account, data and navigation needed to reach the state.
+   - **Action**: the interaction to perform.
+   - **Expected observation**: the visible result that distinguishes success
+     from failure.
+   - **Reason**: the changed requirement or credible regression it checks.
+     Keep the smoke check short without omitting required coverage to meet a
+     time limit. Report access gaps and checks still awaiting the user.
+
+Done when each required manual observation has a reproducible check or a named
+coverage gap. Distinguish agent verification from user checks still pending.

package/skills/hr-manual-qa/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Manual QA"
+  short_description: "Reproducible checks needing human access or judgment"

package/skills/hr-navigation-retro/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-navigation-retro/NOTICE.md

@@ -0,0 +1,5 @@
+# Source notice
+
+The navigation workflow, transcript parser and synthetic tests were written by
+bompus. This bundle distributes no real session transcripts or findings.
+The MIT licence in LICENSE applies to this bundle.

package/skills/hr-navigation-retro/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: hr-navigation-retro
+description: "Audit agent navigation using selected tool-call transcripts: rank misses, widened searches, re-reads and stale-doc remarks, verify findings against current repositories, and propose findability fixes. Use for agent-navigation retrospectives or re-measuring navigation fixes; general project retrospectives are outside this scope."
+argument-hint: "<transcript ...> --repo-root NAME=ROOT"
+disable-model-invocation: true
+---
+
+# Navigation retro
+
+Any coding agent with file and shell access can run this workflow. Find
+navigation failures in recorded tool-call evidence, then verify their causes
+against current source. Ordinary guidance audits belong to
+`hr-agent-guidance-audit`. Changes need their existing implementation authority;
+a request for a retrospective alone authorizes the investigation and proposals.
+
+## Select evidence
+
+1. Read each target repository's guidance and its restrictions on access.
+2. Locate transcripts through the host's existing tools. Select only authorized
+   input files; do not scan every account or transcript store to find them.
+3. Record the repository roots used in those sessions, including each checkout
+   when the same repository appears at several paths. Map each to one name.
+4. Keep transcripts, timelines, metric JSON and reports local. They expose raw
+   prompts, commands, assistant text and paths. Truncation is not redaction.
+
+The bundled [parser](scripts/retro.py) requires Python 3.11 or newer and uses only
+the standard library. It accepts Claude Code and Codex JSONL, OpenCode JSON
+exports, Cursor CLI stream JSON and recorded ACP v1 updates.
+Read [input formats and limits](references/inputs.md) before selecting evidence.
+Its header defines metrics and limitations. It reads selected files, executes no recorded commands and makes
+no network calls. `--json` overwrites its output; choose a task-owned output file.
+`--repo` filters results after analysis and does not restrict which inputs are read.
+
+## Rank and inspect
+
+Resolve the installed skill directory and task scratch directory before running
+these commands. Pass actual selected paths for the placeholders:
+
+```bash
+python3 <skill-directory>/scripts/retro.py rank \
+  --repo-root app=<absolute-recorded-repository-root> \
+  --json <task-scratch>/retro.json \
+  <selected-transcript.jsonl> <another-selected-transcript.jsonl>
+```
+
+All selected events are included by default. Use `--since-days 30` for a dated
+window; undated events are excluded with a warning. If a recording omits its
+working directory, pass its actual recorded directory with `--cwd`.
+
+Repeat `--repo-root` for multiple repositories or checkouts. The most specific
+matching root owns a command; unmapped or unresolved paths remain unknown.
+Use `--subagents` only when the selected subagent transcripts are in scope.
+Report missing inputs and rows omitted by `--min-sessions` or `--min-tools`.
+A heuristic score prioritizes misses, widening and repeated reads. Stale-text
+matches remain visible but do not affect ranking; discussion and quoted examples
+can match. Neither the score nor a repeated read proves a navigation mistake.
+
+Read each top session through its timeline:
+
+```bash
+python3 <skill-directory>/scripts/retro.py timeline <selected-transcript.jsonl>
+```
+
+Record the transcript and tool-call number for each navigation finding.
+Repeated reads during editing may be necessary. Distinguish misses, repeated
+searches and stale instructions from useful revisits. Every inspected session
+gets a verified finding or an explanation that no navigation cause was found.
+
+## Verify and propose
+
+Verify each finding against the repository's fetched default branch.
+Check the path or instruction that caused the search. Search the whole
+repository, including docs, before claiming something is missing.
+Drop findings already fixed or unsupported by current source.
+
+Propose one repair per verified cause. Prefer deleting stale material, moving
+or renaming it to where agents looked, simplifying it, then automating repeated
+steps. Add prose only when those remedies cannot express what is missing.
+
+Record source revision, session evidence, proposed repair and coverage in the
+task's plan. Keep transcript evidence private. Offer implementation within the
+user's existing authorization; do not treat a proposal as permission to apply it.
+
+To assess a repair, compare a post-landing window with the saved baseline.
+Normalize misses, re-reads and stale remarks by tool calls. State changes in
+input coverage and concurrent conditions; totals alone do not show improvement.

package/skills/hr-navigation-retro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HR: Navigation retro"
+policy:
+  allow_implicit_invocation: false

package/skills/hr-navigation-retro/references/inputs.md

@@ -0,0 +1,67 @@
+# Transcript inputs
+
+The agent running the retrospective can use any model provider. Input support
+depends on the application's recording format and the evidence it preserves.
+Select one session per file and pass files explicitly. The parser does not
+discover stores, open databases or export sessions for you.
+
+## Supported formats
+
+- Claude Code JSONL with message tool-use and tool-result blocks.
+- Codex JSONL with session context, function/custom tool calls and their results.
+- OpenCode JSON exports containing `info` and `messages` with `info`/`parts`.
+  Export a selected session with `opencode export <session-id>` into task scratch.
+  Tool parts preserve their native input, output/error and start/end timestamps.
+  Sanitized exports can remove paths and commands needed for attribution.
+- Cursor CLI `--print --output-format stream-json` recordings. Read/write calls
+  and named function calls are supported. Use complete assistant messages;
+  `--stream-partial-output` can duplicate text and is outside this adapter's
+  coverage. Cursor's final-result JSON and text output omit tool events.
+- ACP v1 `session/update` JSONL recordings. Each record can be a JSON-RPC
+  notification, a `{sessionId, update}` envelope or a direct update object.
+  Calls and incremental updates are merged by session and tool-call ID, with
+  one call and one terminal result. This supports agents recording ACP v1,
+  including Grok recordings with this shape, regardless of model provider.
+
+OpenCode and ACP tool names are normalized for read, grep, glob, list, shell,
+write and edit operations. ACP can also supply a tool kind and file locations.
+An unfamiliar tool remains in the total count; its navigation activity may be
+unclassified. ACP display titles are not treated as tool names or shell commands.
+Protocol v2, native Cursor databases, Devin databases and Antigravity protobuf
+stores are outside the native adapters' verified coverage.
+
+## Missing evidence
+
+The parser uses recorded ISO timestamps or numeric Unix seconds/milliseconds.
+ACP itself does not supply timestamps. A recorder can add a top-level
+`timestamp`; Cursor recordings can provide `timestamp_ms`. The parser does not
+invent timestamps from file modification times or the time of analysis.
+
+All selected events are analyzed by default. `--since-days` excludes events
+without usable timestamps and reports undated tool calls on stderr. A file with
+no supported tool calls also produces a warning; an empty report does not prove
+the session had no navigation failures. Inspect warnings alongside metric JSON.
+
+Use `--cwd <absolute-recorded-session-directory>` when a recording omits its
+working directory. Recorded context takes precedence over this fallback. ACP
+session-new/load/resume requests can provide cwd when included in the recording.
+Repository-root mappings label paths; they do not establish a session's cwd.
+Unmapped or unavailable directories remain unknown.
+
+Missing-path checks inspect complete result diagnostics and known shell-result
+JSON envelopes. Fenced examples and arbitrary source JSON are excluded. Unfenced
+source text identical to a diagnostic remains ambiguous; verify the recorded
+command and output before calling it a failure.
+
+Missing result text, terminal references and unsupported tool fields are gaps
+in evidence. They do not establish that a search found nothing. Synthetic tests
+verify these adapters' metric behavior; time or token savings are unmeasured.
+
+## Format references
+
+- [OpenCode export command](https://opencode.ai/docs/cli/#export).
+- [OpenCode SDK tool and message types](https://github.com/anomalyco/opencode/blob/dev/packages/sdk/js/src/gen/types.gen.ts).
+- [Cursor CLI output format](https://cursor.com/docs/cli/reference/output-format).
+- [ACP v1 tool calls and updates](https://agentclientprotocol.com/protocol/v1/tool-calls).
+
+These external references describe input contracts, not installed agent guidance.