inspect-quality

Inspect Quality

HARD GATE — HARD GATE — Quality metrics (coverage, lint, cyclomatic complexity, security scans) must be monitored. If a metric degrades, surface it as a blocker. Do NOT accept regressions.

Run an interactive QA session. The user describes problems they’re encountering. You clarify, explore the codebase for context, and log each issue to specs/bugs/registry.yaml with a structured, durable format.

For each issue the user raises

1. Listen and lightly clarify

Let the user describe the problem in their own words. Ask at most 2–3 short clarifying questions focused on:

What they expected vs what actually happened
Steps to reproduce (if not obvious)
Whether it’s consistent or intermittent

Do NOT over-interview. If the description is clear enough to log, move on.

2. Explore the codebase in the background

Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it’s to:

Learn the domain language used in that area (check specs/UBIQUITOUS_LANGUAGE_LATEST.md if present)
Understand what the feature is supposed to do
Identify the user-facing behavior boundary

3. Assess scope: single issue or breakdown?

Break down when:

The fix spans multiple independent areas
There are clearly separable concerns that could be worked on in parallel
The user describes something with multiple distinct failure modes

Keep as a single issue when:

It’s one behavior that’s wrong in one place
The symptoms are all caused by the same root behavior

4. Log to specs/bugs/registry.yaml

Append the issue to specs/bugs/registry.yaml. Create the specs/bugs/ directory if it doesn’t exist.

registry.yaml format

The file maintains a Markdown table with the following columns (derived from structured audit practice):

Field	Description
`bug_id`	`BUG-YYYY-MM-DDTHHMMSS`
`date`	`YYYY-MM-DD`
`severity`	`critical` / `high` / `medium` / `low`
`priority`	`p0` / `p1` / `p2` / `p3`
`scope`	kebab-case area (e.g. `auth`, `checkout`)
`what_happened`	actual behavior (user-facing terms)
`what_expected`	expected behavior
`steps_to_reproduce`	numbered steps
`root_cause`	one-line hypothesis
`files_changed`	filled in after fix
`approach`	filled in after fix
`risk_level`	`low` / `medium` / `high`
`new_tests`	count (filled in after fix)
`type_check`	`pass` / `fail` (filled in after fix)
`lint`	`pass` / `fail` (filled in after fix)
`commit_type`	`fix` / `fix!` / `feat` (filled in after fix)
`release_type`	`patch` / `minor` / `major` (filled in after fix)
`commit_message`	Conventional Commits message (filled in after fix)
`follow_ups`	semicolon-separated follow-up items
`file`	path to detailed `specs/bugs/BUG-*.md` (filled in by investigate-bug)
`status`	`open` / `in-progress` / `fixed` / `wont-fix`

When a bug is fixed (via validate-fix), update the relevant row with the resolution fields.

Issue body (for context below the table)

For each bug, also append a detail section:

### BUG-YYYY-MM-DDTHHMMSS: [short title]

**What happened:** [actual behavior, plain language]
**What I expected:** [expected behavior]
**Steps to reproduce:**
1. [Step 1]
2. [Step 2]

**Additional context:** [domain-language observations, no file paths]

Rules for all entries

bug_id uses full timestamp: BUG-YYYY-MM-DDTHHMMSS — matches the individual bug file name in specs/bugs/
No file paths or line numbers — these go stale
Use the project’s domain language (check specs/UBIQUITOUS_LANGUAGE_LATEST.md if it exists)
Describe behaviors, not code — “the sync service fails to apply the patch” not “applyPatch() throws”
Reproduction steps are mandatory — if you can’t determine them, ask the user

5. Continue the session

After logging, ask: “Next issue, or are we done?” Keep going until the user says done. Each issue is independent — don’t batch them.