@anhth2/spec-driven-dev-plugin 0.5.0

package/skills/debug/SKILL.md

@@ -0,0 +1,584 @@
+---
+description: Fixes bugs with full workflow (branch, test, commit), performs quick debug analysis of errors or unexpected behavior, or validates traceability coverage between specs and code. Trigger when: "/fix-bug", "/debug", "/validate-traces", "fix bug", "sửa bug", "debug lỗi", "phân tích lỗi", "tại sao lỗi này", "validate traces", "kiểm tra traceability", "coverage matrix", "trace drift".
+---
+
+# Debug & Quality Skills — Fix Bug, Debug, Validate Traces
+
+This skill handles: `/fix-bug` (full bug fix workflow), `/debug` (quick analysis), and `/validate-traces` (traceability coverage check).
+
+---
+
+## /fix-bug — Full Bug Fix Workflow
+
+### Input
+
+Accept: ticket ID (e.g. `PROJ-123`) or a direct bug description.
+
+### Phase 1 — Gather Information
+
+If ticket ID provided:
+- Fetch ticket details if Jira/issue tracker is connected
+- Otherwise ask user to paste: title, steps to reproduce, expected vs actual
+
+If no ticket:
+**CHECKPOINT** — Ask:
+1. Where does the bug occur? (service, endpoint, flow)
+2. Steps to reproduce?
+3. Expected vs Actual behavior?
+4. Error log / stack trace (if any)?
+
+### Phase 2 — Root Cause Analysis
+
+# Context Loader — Load All Project Context
+
+Execute these steps in order. Store everything in memory for the duration of the command session.
+
+**Priority guide (anti-lost-in-middle):**
+- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
+- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
+- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
+- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
+- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+
+---
+
+## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+
+Read `.agent/project-context.yaml`. Extract and store:
+
+**Tech Stack:**
+- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+
+**Conventions:**
+- `conventions.build_command` → how to compile/build
+- `conventions.test_command` → how to run tests
+- `conventions.service_run` → how to start the service
+- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+
+**Domains:**
+- `domains` → list of active business domains
+
+**Paths (if present):**
+- `paths.specs_dir` → BDD specs root
+- `paths.prd_dir` → PRD documents root
+- `paths.refinement_dir` → findings/review output dir
+- `paths.product_definitions_dir` → product definitions root
+- `paths.domain_knowledge_dir` → domain knowledge root
+- `paths.business_dictionary` → path to business-dictionary.md
+- `paths.core_entities` → path to core-entities.md
+- `paths.tech_docs_dir` → technical documentation root
+- `paths.trace_dir` → trace state directory
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs/bdd`
+- `prd_dir` = `specs/prd`
+- `refinement_dir` = `.agent/review`
+- `product_definitions_dir` = `specs/product-definition`
+- `domain_knowledge_dir` = `specs/domain-knowledge`
+- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
+- `core_entities` = `specs/domain-knowledge/core-entities.md`
+- `tech_docs_dir` = `tech-docs`
+- `trace_dir` = `.trace`
+
+If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+
+---
+
+## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+
+If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
+Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
+If the file does not exist → skip silently.
+
+---
+
+## Step 3 — [CRITICAL] Load CLAUDE.md
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+Read `CLAUDE.md`. Extract and store:
+
+- **§1 Project Overview** → project name, language, framework, build/test commands, domains
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
+- **§7 Git Conventions** → branch naming pattern, commit message format
+
+If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+
+---
+
+## Step 4 — [SAFETY] Load Data Protection Rules
+
+Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+
+Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+
+If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+
+---
+
+## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+
+Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+
+If it exists, read it and extract:
+- **Canonical Terms** → complete list of approved terms and their definitions
+- **Banned Terms** → complete list of banned terms and their canonical replacements
+- **Status / Enum Registry** → allowed enum values per entity
+
+Store the banned terms list for **active enforcement** throughout the command session:
+- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
+- Replace banned terms with their canonical equivalents automatically
+
+If the file does not exist → skip silently. Do not warn or block.
+
+---
+
+## Step 6 — [DOMAIN] Load Core Entities (conditional)
+
+Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
+Default path: `specs/domain-knowledge/core-entities.md`.
+
+If it exists, read it and store:
+- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
+- **Field name registry** → canonical field names to use in generated code and documents
+- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+
+**How to use this catalog:**
+- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
+- When generating PRD/BDD: reference entity names from this catalog for consistency
+- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+
+If the file does not exist → skip silently.
+
+---
+
+## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+
+After loading all context, synthesize and output a compact summary block.
+This recap ensures the most critical facts are stated at the END of context loading
+(recency effect — freshest in working memory when the task begins).
+
+Output exactly this block:
+```
+[CTX LOADED]
+Stack     : {language} / {framework} / {database}
+Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Ticket    : {ticket_prefix}-
+Dict      : {loaded — N canonical terms, M banned terms | missing}
+Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+```
+
+If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+
+---
+
+## Context Load Complete
+
+After completing all steps, you have loaded:
+- Project identity, tech stack, module conventions
+- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
+- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
+- Data protection rules (sensitive file patterns to never access)
+- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
+- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
+- All configured paths
+
+Proceed to the next step of the calling command.
+
+
+Trace through layers (from CLAUDE.md architecture):
+1. Identify the service/module from the failing endpoint/feature
+2. Read relevant code files, layer by layer
+3. Match against common bug patterns:
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong response data | Data mapping layer | Check field mapping, DTO conversions |
+| 400 Bad Request | Input validation | Check DTO constraints, required fields |
+| 403 Forbidden | Auth configuration | Check role-based access rules |
+| 404 Not Found | Repository query | Check find method, ID types |
+| Slow query / N+1 | Data access layer | Check for missing JOIN FETCH or batch loading |
+| Null Pointer | Missing null checks, optional not handled | Check Optional.orElseThrow usage |
+| Transaction rollback | Missing/wrong transaction scope | Check @Transactional on service methods |
+| Stale cache | Missing cache eviction after write | Check cache invalidation on write operations |
+| Type mismatch in query | Filter/specification code | Check field types in query predicates |
+| Cross-service timeout | External service call | Check URL config, fallback behavior |
+
+**CHECKPOINT — Root Cause Report:**
+
+```
+Root Cause Analysis — {TICKET_ID}:
+
+Bug: {description}
+Affected module: {module/service}
+Root cause: {specific technical analysis}
+Affected files:
+  - {file}: {what's wrong}
+
+Proposed fix:
+  - {file}: {what to change}
+
+Regression risk: Low / Medium / High
+  → Reason: {explanation}
+
+Proceed with fix? (Y/N)
+```
+
+Wait for user confirmation.
+
+### Phase 3 — Implement Fix
+
+```bash
+git checkout -b fix/{TICKET_ID}-{short-description}
+```
+
+Apply the fix exactly as analyzed. Follow CLAUDE.md coding standards — do not introduce new violations.
+
+Add traceability annotation if the file has `@trace.implements`:
+```
+// @trace.implements={UC-ID}-SC{N}
+// @trace.fixes={TICKET_ID}
+// @trace.root_cause={brief description}
+```
+
+### Phase 4 — Regression Test
+
+Generate a regression test if one doesn't exist:
+```
+// @trace.verifies={UC-ID}
+// @trace.regression={TICKET_ID}
+Test: "Regression {TICKET_ID}: {bug description}"
+  → Reproduce the exact bug scenario
+  → Assert the fix works correctly
+```
+
+Run the test: `{TEST_COMMAND_FOR_CLASS}`
+
+If test fails → debug and fix (max 3 iterations).
+
+### Phase 5 — Build Verify
+
+```bash
+{BUILD_COMMAND}   # max 3 retries
+```
+
+### Phase 6 — Commit & Push
+
+```bash
+git add {changed files}
+git commit -m "fix({TICKET_ID}): {brief description}"
+git push -u origin fix/{TICKET_ID}-{slug}
+```
+
+### Output
+
+```
+/fix-bug Complete — {TICKET_ID}
+
+## Root Cause
+{analysis}
+
+## Changes
+- {file}: {what changed and why}
+
+## Regression Test
+✅ Added: {TestClass}.{method}
+✅ Build: SUCCESS
+
+## Branch
+fix/{TICKET_ID}-{slug}
+```
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+
+
+---
+
+## /debug — Quick Debug Analysis
+
+Use when: IDE shows an error, test fails unexpectedly, behavior is strange, or you need to understand why code does something.
+
+**Different from `/fix-bug`**: This is analysis only, no full workflow, no ticket required.
+
+### Input
+
+Paste one of:
+1. Stack trace / error log
+2. Test failure output
+3. File path + description of unexpected behavior
+4. A specific question about a code snippet
+
+### Stack Trace Analysis
+
+Read stack trace from **bottom up** — the `Caused by:` line is the real root cause.
+
+```
+Caused by: {RealException}  ← start here
+  at {class}.{method}({file}:{line})  ← trace from here
+  ...
+  at {entrypoint}  ← where it was called from
+```
+
+### Common Error Patterns
+
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| NullPointerException | Accessing field on null object; Optional not handled | Check Optional.orElseThrow, null guards |
+| ClassCastException | Wrong type assumption; incorrect generic usage | Check type at assignment/return point |
+| OutOfMemoryError | Loading too much data; memory leak | Add pagination, check collection sizes |
+| StackOverflowError | Infinite recursion | Find recursive call with no base case |
+| Connection refused | Dependency service not running | Check config URLs, start dependent service |
+| Authentication/401 | Token expired, wrong config, missing header | Verify token, check auth config |
+| Permission denied/403 | Wrong role in request or misconfigured access rules | Check auth annotations and role config |
+| Database constraint violation | Duplicate key, missing FK, null in NOT NULL column | Check data and constraint definitions |
+| Serialization error | Circular reference, unmapped field | Check DTO/mapper configuration |
+| Test assertion mismatch | Wrong mock setup or wrong expected value | Re-read mock setup and assertion logic |
+
+### Test Failure Analysis
+
+```
+Expected: {expected value}
+Actual  : {actual value}
+  at {test class}.{method}(line {N})
+```
+
+1. What is the gap between Expected and Actual?
+2. Trace to the exact test line
+3. Is the mock setup correct? (`given(...).willReturn(...)`)
+4. Is the assertion logically correct?
+
+### Output
+
+```
+/debug Analysis
+
+## Error Encountered
+{description}
+
+## Root Cause
+{technical explanation}
+
+## Location in Code
+File: {path}
+Line: {line number if available}
+Layer: {Controller/Service/Repository/Test}
+
+## Suggested Fix
+{specific code change}
+
+## Related Rule
+See CLAUDE.md §{section} — {section name}
+
+## Next Step
+- To fully fix → run /fix-bug {TICKET_ID}
+- Just needed analysis → done here
+```
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+
+
+---
+
+## /validate-traces — Traceability Coverage Matrix
+
+Read-only check of coverage between specs, code, and tests.
+
+### Input
+
+Accept: domain name or specific UC-ID.
+
+### Process
+
+1. **Read .feature files** → collect all SC-IDs for the domain/UC
+2. **Scan controller files** → find `@trace.implements` tags
+3. **Scan test files** → find `@trace.verifies` tags
+4. **Read `.trace/{UC-ID}.tsv`** → check for drift (scenario text changed since last code gen)
+
+### Output
+
+```
+/validate-traces — {domain}
+
+| UC-ID | SC | Spec | Code | Test | Status |
+|-------|----|------|------|------|--------|
+| {UC}-UC1 | SC1 | ✅ | ✅ {ControllerClass} | ✅ {TestClass} | synced |
+| {UC}-UC1 | SC2 | ✅ | ✅ {ControllerClass} | ❌ MISSING | gap |
+| {UC}-UC2 | SC1 | ✅ | ❌ MISSING | ❌ MISSING | gap |
+
+Gaps:
+  Missing code: [{UC-ID}-SC2, {UC-ID2}-SC1]
+  Missing tests: [{UC-ID}-SC1]
+  Drifted (spec changed, code not updated): [{list}]
+
+Recommendations:
+  - /generate-code {UC-ID} SC2
+  - /generate-tests {UC-ID}
+  - Re-run /generate-code {UC-ID} for drifted scenarios
+```
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+