ai-core-framework 0.1.0

package/core/skills/qa-report-bug/SKILL.md

@@ -0,0 +1,518 @@
+---
+name: qa-report-bug
+description: Use when the user asks to run /report-bug, file a bug from a reproducer, capture severity and environment details, or create a bug ticket from QA findings.
+command: /report-bug
+display_name: "Report Bug"
+version: 1.0.0
+owner_agent: qa-tester
+# Also invokable by: any agent/user who discovers a bug
+model_preference: sonnet
+args:
+  - name: title
+    required: true
+    type: string
+    description: "Short bug title"
+  - name: severity
+    required: false
+    type: string
+    enum: [SEV-1, SEV-2, SEV-3, SEV-4, auto]
+    default: "auto"
+    description: "Severity (auto = AI assesses)"
+preconditions:
+  - has_reproducer: true
+  - has_environment_info: true
+postconditions:
+  - bug_ticket_created: true
+  - bug_status: NEW
+  - triage_notified: true
+  - sev1_escalated: "if applicable"
+---
+
+# /report-bug
+
+> File a well-formed bug report. Quality gate: no ambiguous reports.
+
+## 🎯 Purpose
+
+Create bug ticket that developer can actually fix. Enforce:
+1. Clear reproducer (copy-pasteable)
+2. Expected vs actual behavior
+3. Environment details
+4. Severity assessment
+5. Evidence (logs, screenshots)
+
+Bad bug reports waste dev time → strict template enforcement here.
+
+## 🚦 Trigger
+
+**Manual**:
+```
+/report-bug "Login returns 500 for emails with +"
+/report-bug "Checkout crashes when cart has 100+ items" --severity=SEV-2
+```
+
+**Auto**:
+- From `/smoke-test` when tests fail
+- From `/verify-fix` when bug still exists or new bug found
+
+## 📋 Preconditions (STRICT)
+
+### 1. Has reproducer
+User/agent MUST provide:
+- Steps to reproduce
+- Environment (where observed)
+
+If not → prompt interactive collection.
+
+### 2. Not duplicate
+Check existing open bugs for similar:
+- Grep bug titles in `project/bugs/*.json`
+- If > 80% similarity → flag, ask if linking to existing
+
+### 3. Has evidence (soft requirement)
+Ideally: screenshot, log excerpt, network trace.
+If missing, still accept but flag in bug.
+
+## 🔄 Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Collect info                                     │
+│   If args incomplete, interactive collection:            │
+│   - Title (clear, specific)                              │
+│   - Steps to reproduce                                   │
+│   - Expected behavior                                    │
+│   - Actual behavior                                      │
+│   - Environment (OS, browser, env name, build)           │
+│   - Frequency (always, sometimes, once)                  │
+│   - Evidence (screenshot/log)                            │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Validate reproducer                              │
+│   - Steps numbered, clear                                │
+│   - No ambiguous phrases ("sometimes breaks")            │
+│   - Expected != Actual (not just confusion)              │
+│   If fails: request clarification                        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Check for duplicates                             │
+│   - Search by title similarity                           │
+│   - Search by symptom keywords                           │
+│   If found: offer to link as duplicate                   │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Assess severity                                  │
+│   If --severity=auto:                                    │
+│     Rules (see RULE RB-003):                             │
+│     - Data loss / security / prod down → SEV-1           │
+│     - Major feature broken, no workaround → SEV-2        │
+│     - Minor broken, workaround exists → SEV-3            │
+│     - Cosmetic, edge case → SEV-4                        │
+│   Else: use provided severity                            │
+│                                                          │
+│   Validate: reasoning supports severity                  │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Determine impact                                 │
+│   - Users affected: all | many | few | specific segment  │
+│   - Business impact: revenue / reputation / operations   │
+│   - Security impact: if any                              │
+│   - Data impact: if any                                  │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Identify related                                 │
+│   - Feature ticket (if relates to recent feature)        │
+│   - Similar past bugs                                    │
+│   - Relevant ADRs                                        │
+│   - Components affected                                  │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Generate bug ID                                  │
+│   BUG-NNN (separate sequence from TICKET-)               │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Create bug ticket                                │
+│   Path: project/bugs/BUG-NNN.json                 │
+│   Follow template: templates/qa/bug-report-template.md  │
+│   Initial status: NEW                                    │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: SEV-1 special handling                           │
+│   If SEV-1:                                              │
+│   - Console: 🚨 SEV-1 BUG FILED                          │
+│   - Immediate HANDOFF → scrum-master + tech-lead         │
+│   - Suggest: /hotfix BUG-NNN                             │
+│   - (Optional) Pager/Slack urgent notification           │
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Normal handoff                                  │
+│   HANDOFF → scrum-master for triage                      │
+│   Suggest: /triage-bug BUG-NNN                           │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE RB-001: Reproducer quality gate
+**MUST** reject vague reports. Examples of unacceptable:
+- ❌ "Login doesn't work"
+- ❌ "Page is broken"
+- ❌ "Sometimes it fails"
+
+Require:
+- ✅ Specific conditions
+- ✅ Exact steps
+- ✅ Observable outcome
+
+If user insists on filing anyway → file with NEEDS_MORE_INFO status, not NEW.
+
+### RULE RB-002: No sensitive data
+**MUST NOT** include:
+- Real passwords, tokens, session cookies
+- Customer PII (emails unless test account, credit cards, SSNs)
+- Internal secret URLs
+
+Redact as `[REDACTED_PASSWORD]`, `user+XXX@example.com`, etc.
+
+### RULE RB-003: Severity assessment rigorous
+**MUST** justify severity with:
+- User impact (how many, what percentage)
+- Business impact (financial, reputational, legal)
+- Workaround availability
+- Data/security implications
+
+No severity inflation (everything SEV-1) or deflation (SEV-1 marked SEV-3 to avoid interrupting).
+
+Severity matrix:
+
+| Criterion | SEV-1 | SEV-2 | SEV-3 | SEV-4 |
+|-----------|-------|-------|-------|-------|
+| Users affected | All / critical | Many / important | Few | Isolated |
+| Data loss | Yes | Possible | No | No |
+| Security breach | Yes | Possible | No | No |
+| Production impact | Down / failing | Degraded | Minor | None |
+| Workaround | No | Difficult | Exists | Trivial |
+
+### RULE RB-004: SEV-1 immediate escalation
+**MUST** notify tech-lead + scrum-master immediately:
+- Before typing full report (if observing SEV-1)
+- Console output: `🚨 SEV-1`
+- Even at 3am, file + escalate
+
+Don't "wait until tomorrow" for SEV-1.
+
+### RULE RB-005: No fix suggestions required
+Bug reporter **NOT required** to suggest fix. But **MAY** include hypothesis (helpful for dev).
+
+If hypothesis included, label it clearly as "Hypothesis (not verified)".
+
+### RULE RB-006: Link to related
+**MUST** link:
+- Feature ticket (if bug in recent feature) → helps code context
+- Similar past bugs → helps pattern recognition
+
+### RULE RB-007: Environment completeness
+**MUST** capture:
+- Environment name (dev/staging/prod)
+- Build version / commit SHA
+- Browser + version (for UI)
+- OS + version
+- Date/time observed
+- User agent (for UI)
+
+Missing env info = bug 50% harder to fix.
+
+### RULE RB-008: Frequency honest
+**MUST** report actual frequency:
+- Always (10/10)
+- Usually (7/10)
+- Sometimes (3-5/10)
+- Rarely (1/10)
+- Once (1/1, cannot re-test)
+
+Don't say "always" if not sure.
+
+### RULE RB-009: Evidence preservation
+Screenshots, logs, HAR files → save to `project/bugs/evidence/BUG-NNN/`.
+
+Don't paste long logs in bug body → link to file.
+
+### RULE RB-010: No emotions in reports
+**MUST NOT** include:
+- Frustration language ("this is terrible")
+- Blame ("developer broke everything")
+- Customer language not useful for fixing
+
+Stay factual. Reporter frustration is valid but doesn't help fix.
+
+## 📥 Input Examples
+
+### Example 1: Full form
+```
+/report-bug "Login returns 500 for emails containing +"
+
+Steps:
+1. Go to /login
+2. Enter email: "user+tag@example.com"
+3. Enter any password
+4. Click Login
+
+Expected: Normal login flow (success or invalid credentials error)
+Actual: HTTP 500, white error page
+
+Environment: staging, build v1.2.0-rc.3
+Browser: Chrome 134, macOS 14.4
+Frequency: Always (5/5)
+```
+
+### Example 2: Minimal (will prompt)
+```
+/report-bug "Cart broken"
+```
+Expected response: Interactive collection of missing info.
+
+### Example 3: Auto-severity
+```
+/report-bug "Customer DB shows 0 rows on dashboard"
+```
+Auto assess: Data integrity concern → SEV-1.
+
+## 📤 Output Format (Created)
+
+```markdown
+## 🐛 Bug Filed: BUG-005
+
+**Title**: Login returns 500 for emails containing +
+**Severity**: SEV-2 (assessed automatically)
+**Status**: NEW
+**Filed by**: qa-tester-agent
+**Filed**: 2026-04-18 19:00 UTC
+
+### Reproducer
+
+**Steps**:
+1. Go to https://staging.app/login
+2. Enter email: `user+tag@example.com` (any plus sign in local part)
+3. Enter any password
+4. Click "Log in" button
+
+**Expected**: Normal login flow — either successful login or "Invalid credentials" error message
+**Actual**: HTTP 500 response, white error page with "Something went wrong"
+
+### Environment
+| Field | Value |
+|-------|-------|
+| Environment | staging |
+| Build | v1.2.0-rc.3 |
+| Commit | abc1234 |
+| Browser | Chrome 134.0.6998.88 |
+| OS | macOS 14.4 |
+| Observed | 2026-04-18 18:45 UTC |
+
+### Frequency
+Always (5/5 attempts)
+
+### Evidence
+- Screenshot: `project/bugs/evidence/BUG-005/screenshot-1.png`
+- Network trace: `project/bugs/evidence/BUG-005/har.json`
+- Server log excerpt:
+  ```
+  2026-04-18T18:45:23Z ERROR handler/login.ts:42 
+    Unhandled exception: InvalidEmailError
+    at validateEmail (src/auth/validators.ts:67)
+    at loginHandler (src/handlers/login.ts:34)
+    Email input: "user tag@example.com"  <-- Note: space, not +!
+  ```
+
+### Severity Assessment
+
+**SEV-2** because:
+- Users affected: ~2-5% (emails with +)
+- No workaround (users cannot log in)
+- Core functionality broken (login)
+- No data loss
+- No security issue
+
+Not SEV-1 because:
+- Not all users affected
+- Production still working for majority
+- Not data loss / security
+
+### Impact Analysis
+- **User count**: Estimated 2-5% of user base use + in emails (Gmail aliases common)
+- **Business**: Revenue impact from locked-out users
+- **Customer support**: Likely support tickets if deployed to prod
+
+### Hypothesis (not verified)
+
+Looking at log: "user tag@example.com" instead of "user+tag@example.com"
+
+Likely: URL decoding treating + as space (classic `encodeURIComponent` vs `+` issue). Form encoding should preserve + in email field.
+
+### Related
+
+- **Feature**: None (auth system, no recent changes)
+- **Similar past bugs**: None found
+- **Components**: `src/handlers/login.ts`, `src/auth/validators.ts`
+- **ADRs**: ADR-0003 (authentication strategy)
+
+### Ticket File
+
+Created: `project/bugs/BUG-005.json`
+
+### Next Steps
+
+1. **Scrum Master**: `/triage-bug BUG-005` (confirm severity, assign sprint)
+2. **Tech Lead**: Review hypothesis, assign dev
+3. **Developer**: Fix + add regression test per RULE TEST-008
+4. **QA**: `/verify-fix BUG-005` after fix deploys
+
+---
+HANDOFF → scrum-master
+Action: /triage-bug BUG-005
+```
+
+## 📤 Output Format (SEV-1)
+
+```markdown
+## 🚨 SEV-1 BUG FILED: BUG-006
+
+**🚨 IMMEDIATE ACTION REQUIRED 🚨**
+
+**Title**: Payment processing fails - all transactions returning error
+**Severity**: SEV-1 (CRITICAL)
+**Status**: NEW
+**Filed**: 2026-04-18 19:15 UTC
+
+### Impact
+- **Production**: DOWN (payments)
+- **Users affected**: 100% of purchase attempts
+- **Revenue impact**: ~$5K/hour lost
+- **Duration**: Started 19:00 UTC (15 min ago)
+
+### Reproducer
+[Steps included]
+
+### Evidence
+[Screenshots + error logs]
+
+### Hypothesis
+[If any]
+
+### 🚨 Immediate Actions
+
+1. **Scrum Master**: Declare incident, notify stakeholders
+2. **Tech Lead**: `/hotfix BUG-006` NOW
+3. **DevOps**: Check recent deploys, consider rollback
+4. **Customer Success**: Prepare comms if not resolved in 30 min
+
+### Escalation
+
+- [x] Tech Lead notified
+- [x] Scrum Master notified
+- [ ] Engineering Manager (if not resolved in 1h)
+- [ ] Executive team (if not resolved in 2h)
+
+### Ticket File
+Created: `project/bugs/BUG-006.json`
+
+---
+HANDOFF → tech-lead + scrum-master (URGENT)
+Action: /hotfix BUG-006 immediately
+```
+
+## 📤 Output Format (Duplicate)
+
+```markdown
+## ⚠️ Possible Duplicate
+
+**Attempted to file**: "Login returns 500 for emails with +"
+
+### Existing similar bug:
+- **BUG-003**: "Login 500 error for certain email formats"
+  - Status: IN_PROGRESS
+  - Assigned: @developer-alice
+  - Created: 2026-04-17 (1 day ago)
+  - Similarity: 92%
+
+### Options
+
+1. **Link as related**: Add your evidence to BUG-003 (recommended)
+   → `/comment BUG-003 "Also reproducible with + character..."`
+
+2. **File as new**: If you believe it's different
+   → `/report-bug ... --force-new --link-to=BUG-003`
+
+3. **Cancel**: Do nothing (already tracked)
+
+What would you like to do?
+```
+
+## 📤 Output Format (Reject Low Quality)
+
+```markdown
+## ❌ Cannot File Bug - Insufficient Info
+
+**Attempted**: "Login is broken"
+
+### Missing required information
+
+- [ ] **Steps to reproduce**: What did you do exactly?
+- [ ] **Expected**: What should happen?
+- [ ] **Actual**: What does happen?
+- [ ] **Environment**: Where did you see this?
+- [ ] **Frequency**: Every time? Sometimes? Once?
+
+### Why this matters
+
+Developer cannot fix "broken" — needs specific scenario. Example of good bug:
+
+> Login returns 500 for emails with + sign.
+> Steps: 1) Go to /login, 2) Enter "user+x@y.com", 3) Click login
+> Expected: Normal flow. Actual: HTTP 500.
+> Env: staging, Chrome 134. Always happens.
+
+### Options
+
+1. **Refile with details**:
+   ```
+   /report-bug "Login returns 500 for emails with +"
+   ```
+   (Provide full info when prompted)
+
+2. **Get help**: Ask scrum-master to help reproduce and file
+
+### No bug filed.
+```
+
+## 🚨 Failure Modes
+
+| Scenario | Action |
+|----------|--------|
+| No reproducer | Interactive collection or reject |
+| Duplicate found | Suggest linking to existing |
+| Ambiguous severity | AI suggests, human confirms |
+| SEV-1 after hours | File + page on-call immediately |
+| Reporter gave bad info | Diplomatic pushback, guide to quality |
+| Evidence file too large | Store in core, link reference |
+
+## 🔗 Related Commands
+
+- **Before**: `/smoke-test` (often finds bugs) or manual discovery
+- **After**:
+  - SEV-1: `/hotfix`
+  - Normal: `/triage-bug`
+  - After fix: `/verify-fix`
+- **Alternative**: `/feedback` (for feature requests, not bugs)
+
+## 📊 Metrics Tracked
+
+```json
+{
+  "timestamp": "2026-04-18T19:00:00Z",
+  "bug_id": "BUG-005",
+  "reporter": "qa-tester-agent",
+  "severity": "SEV-2",
+  "has_reproducer": true,
+  "has_evidence": true,
+  "auto_severity": true,
+  "duplicate_of": null,
+  "sev1_escalated": false,
+  "duration_to_file_minutes": 4
+}
+```
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: QA Lead