Cursor rule

1---
2description: "Interactive QA session where user reports bugs or issues conversationally, and the agent logs them to specs/bugs/registry.yaml with a structured audit schema. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, or mentions \"QA session\"."
3alwaysApply: false
4---
5 
6# Inspect Quality
7> **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.
8 
9 
10Run 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.
11 
12## For each issue the user raises
13 
14### 1. Listen and lightly clarify
15 
16Let the user describe the problem in their own words. Ask **at most 2–3 short clarifying questions** focused on:
17 
18- What they expected vs what actually happened
19- Steps to reproduce (if not obvious)
20- Whether it's consistent or intermittent
21 
22Do NOT over-interview. If the description is clear enough to log, move on.
23 
24### 2. Explore the codebase in the background
25 
26Kick off an Agent (subagent_type=Explore) to understand the relevant area. The goal is NOT to find a fix — it's to:
27 
28- Learn the domain language used in that area (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if present)
29- Understand what the feature is supposed to do
30- Identify the user-facing behavior boundary
31 
32### 3. Assess scope: single issue or breakdown?
33 
34Break down when:
35 
36- The fix spans multiple independent areas
37- There are clearly separable concerns that could be worked on in parallel
38- The user describes something with multiple distinct failure modes
39 
40Keep as a single issue when:
41 
42- It's one behavior that's wrong in one place
43- The symptoms are all caused by the same root behavior
44 
45### 4. Log to specs/bugs/registry.yaml
46 
47Append the issue to `specs/bugs/registry.yaml`. Create the `specs/bugs/` directory if it doesn't exist.
48 
49#### registry.yaml format
50 
51The file maintains a Markdown table with the following columns (derived from structured audit practice):
52 
53| Field | Description |
54|-------|-------------|
55| `bug_id` | `BUG-YYYY-MM-DDTHHMMSS` |
56| `date` | `YYYY-MM-DD` |
57| `severity` | `critical` / `high` / `medium` / `low` |
58| `priority` | `p0` / `p1` / `p2` / `p3` |
59| `scope` | kebab-case area (e.g. `auth`, `checkout`) |
60| `what_happened` | actual behavior (user-facing terms) |
61| `what_expected` | expected behavior |
62| `steps_to_reproduce` | numbered steps |
63| `root_cause` | one-line hypothesis |
64| `files_changed` | filled in after fix |
65| `approach` | filled in after fix |
66| `risk_level` | `low` / `medium` / `high` |
67| `new_tests` | count (filled in after fix) |
68| `type_check` | `pass` / `fail` (filled in after fix) |
69| `lint` | `pass` / `fail` (filled in after fix) |
70| `commit_type` | `fix` / `fix!` / `feat` (filled in after fix) |
71| `release_type` | `patch` / `minor` / `major` (filled in after fix) |
72| `commit_message` | Conventional Commits message (filled in after fix) |
73| `follow_ups` | semicolon-separated follow-up items |
74| `file` | path to detailed `specs/bugs/BUG-*.md` (filled in by investigate-bug) |
75| `status` | `open` / `in-progress` / `fixed` / `wont-fix` |
76 
77When a bug is fixed (via `validate-fix`), update the relevant row with the resolution fields.
78 
79#### Issue body (for context below the table)
80 
81For each bug, also append a detail section:
82 
83```markdown
84### BUG-YYYY-MM-DDTHHMMSS: [short title]
85 
86**What happened:** [actual behavior, plain language]
87**What I expected:** [expected behavior]
88**Steps to reproduce:**
891. [Step 1]
902. [Step 2]
91 
92**Additional context:** [domain-language observations, no file paths]
93```
94 
95#### Rules for all entries
96 
97- **bug_id** uses full timestamp: `BUG-YYYY-MM-DDTHHMMSS` — matches the individual bug file name in `specs/bugs/`
98- **No file paths or line numbers** — these go stale
99- **Use the project's domain language** (check `specs/UBIQUITOUS_LANGUAGE_LATEST.md` if it exists)
100- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws"
101- **Reproduction steps are mandatory** — if you can't determine them, ask the user
102 
103### 5. Continue the session
104 
105After logging, ask: "Next issue, or are we done?" Keep going until the user says done. Each issue is independent — don't batch them.
106