@anionzo/skill 1.4.0 → 1.6.0

package/skills/debug/SKILL.md

@@ -0,0 +1,252 @@
+# Debug
+
+## Purpose
+
+Systematically diagnose and fix errors through structured investigation, root cause analysis, and verified resolution.
+
+This skill exists to prevent fixing symptoms without understanding root causes, and to enforce the discipline of evidence-based debugging over guesswork.
+
+## When To Use
+
+Load this skill when:
+
+- a build fails (compilation, type error, missing dependency)
+- a test fails (assertion mismatch, timeout, flaky)
+- a runtime crash or exception occurs
+- an integration failure happens (API mismatch, env config, auth)
+- a user reports a bug or regression
+- a task is blocked with unclear cause
+- the user says "debug this", "fix this error", "why is this failing", or "investigate this"
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you have not completed Phase 1, you cannot propose fixes. Symptom fixes are failure.
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Investigate — Find the Root Cause
+
+**BEFORE attempting ANY fix:**
+
+#### 1a. Classify the Issue
+
+Classify before investigating. Misclassifying wastes time.
+
+| Type | Signals |
+|---|---|
+| **Build failure** | Compilation error, type error, missing module, bundler failure |
+| **Test failure** | Assertion mismatch, snapshot diff, timeout, flaky intermittent |
+| **Runtime error** | Crash, uncaught exception, undefined behavior |
+| **Integration failure** | HTTP 4xx/5xx, env variable missing, API schema mismatch |
+| **Blocked task** | Circular dependency, conflicting changes, unclear requirement |
+
+**Output:** One-line classification: `[TYPE] in [component]: [symptom]`
+
+#### 1b. Reproduce
+
+Run the exact failing command verbatim:
+
+```bash
+<failing-command> 2>&1
+```
+
+- Capture error output verbatim. Exact line numbers and messages matter.
+- Run twice — if intermittent, classify as flaky (check shared state, race conditions, test ordering).
+- If the command cannot be reproduced, note that explicitly and gather more data. Do not guess.
+
+#### 1c. Read Implicated Files
+
+Read exactly the files mentioned in the error output. Do not read the entire codebase.
+
+#### 1d. Check Recent Changes
+
+```bash
+git log --oneline -10
+git diff HEAD~3 -- <failing-file>
+```
+
+If a recent commit introduced the failure, the fix is likely adjusting that change.
+
+#### 1e. Multi-Component Diagnostics
+
+When the system has multiple components (CI -> build -> deploy, API -> service -> database):
+
+Add diagnostic instrumentation at EACH component boundary BEFORE proposing fixes:
+
+```
+For EACH component boundary:
+  - Log what data enters the component
+  - Log what data exits the component
+  - Verify environment/config propagation
+  - Check state at each layer
+
+Run once to gather evidence showing WHERE it breaks
+THEN analyze evidence to identify the failing component
+THEN investigate that specific component
+```
+
+#### 1f. Narrow to Root Cause
+
+Write a one-sentence root cause:
+
+> Root cause: `<file>:<line>` — `<what is wrong and why>`
+
+**If you cannot write this sentence, you do not have the root cause yet. Do NOT proceed to Phase 2.**
+
+### Phase 2: Analyze — Find the Pattern
+
+#### 2a. Find Working Examples
+
+Locate similar working code in the same codebase. What works that is similar to what is broken?
+
+#### 2b. Compare Against References
+
+If implementing a pattern, read the reference implementation COMPLETELY. Do not skim.
+
+#### 2c. Identify Differences
+
+What is different between working and broken? List every difference, however small. Do not assume "that can't matter."
+
+#### 2d. Form Hypothesis
+
+State clearly: "I think X is the root cause because Y."
+
+Be specific, not vague. Write it down.
+
+### Phase 3: Fix — Implement and Verify
+
+#### 3a. Small Fix (1-3 files, obvious change)
+
+- Implement directly
+- Run verification immediately
+
+#### 3b. Substantial Fix (cross-cutting, logic redesign)
+
+- Consider whether the fix needs its own plan (hand off to `planning`)
+- Document the root cause and fix approach before implementing
+
+#### 3c. Verify the Fix
+
+Run the exact command that originally failed. It must pass cleanly:
+
+```bash
+<original-failing-command>
+```
+
+Also run broader checks for regressions:
+
+```bash
+# Project-specific build/test/lint — adapt to your project
+```
+
+**If verification fails, return to Phase 1 with new information. Do NOT report success.**
+
+#### 3d. Escalation: 3+ Failed Fixes
+
+Count how many fixes you have attempted.
+
+- **< 3 fixes failed:** Return to Phase 1, re-analyze with new information.
+- **>= 3 fixes failed: STOP.** Question the architecture.
+
+Signs of an architectural problem:
+
+- Each fix reveals new shared state, coupling, or problems in different places
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+**Stop and discuss with the user before attempting more fixes.** This is not a failed hypothesis — this is a wrong architecture.
+
+### Phase 4: Learn — Capture the Pattern
+
+Ask: would knowing this save 15+ minutes in a future session?
+
+If yes, document the pattern:
+
+```markdown
+## [Classification]
+
+**Root cause:** [one sentence]
+**Signal:** [how to recognize this pattern]
+**Fix:** [what resolves it]
+```
+
+Consider handing off to `extract` for significant learnings.
+
+## Quick Reference
+
+| Situation | First action |
+|---|---|
+| Build fails | `git log --oneline -10` — check recent changes |
+| Test fails | Run test verbatim, capture exact assertion output |
+| Flaky test | Run 5x — if intermittent, check shared state/ordering |
+| Runtime crash | Read stack trace top-to-bottom, find first line in your code |
+| Integration error | Check env vars, then API response body (not just status code) |
+| Bug report | Restate symptom, then reproduce or explain why reproduction is blocked |
+| 3+ fixes failed | Stop fixing. Question the architecture. |
+
+## Output Format
+
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what was debugged and whether it is fixed
+2. **Key Details:**
+   - classification and root cause (one-line each)
+   - reproduction status
+   - what was changed to fix it
+   - verification result (pass/fail)
+   - number of fix attempts if > 1
+   - whether a learning was captured
+3. **Next Action** — only when a natural follow-up exists:
+   - fix applied → resume implementation with `feature-delivery`
+   - fix revealed a pattern → `extract`
+   - fix needs review → `code-review`
+   - fix is non-trivial → `planning` before implementation
+   - 3+ fixes failed → discuss architecture with user
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I see the problem, let me fix it" | Seeing symptoms is not understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures signals architectural problem. Question the pattern. |
+| "Quick fix for now, investigate later" | Later never comes. Fix properly now. |
+
+## Red Flags
+
+- fixing symptoms without identifying root cause
+- skipping reproduction — diagnosing from error message alone
+- guessing the fix without reading the implicated code
+- proposing fixes before tracing data flow
+- committing a fix without running verification
+- proposing a rewrite before understanding the current failure
+- changing many files before narrowing the cause
+- not capturing a learning when the fix took more than 15 minutes to find
+- declaring "should work now" without running the failing command again
+- attempting fix #4+ without questioning the architecture
+
+## Checklist
+
+- [ ] Issue classified (one-line)
+- [ ] Reproduced with exact command
+- [ ] Implicated files read
+- [ ] Recent changes checked
+- [ ] Root cause identified (one sentence with file:line)
+- [ ] Working example compared (if applicable)
+- [ ] Fix applied
+- [ ] Fix verified (original command passes)
+- [ ] Regression check run
+- [ ] Fix attempt count tracked (escalate at 3+)
+- [ ] Learning captured (if pattern is new/useful)
+
+## Done Criteria
+
+This skill is complete when the root cause is identified, the fix is verified with the originally failing command, and a regression check has been run. If 3+ fixes have failed, the skill is complete when the architectural concern has been raised with the user. If the fix cannot be completed, the skill is complete when the root cause and blocker are documented.

package/skills/debug/examples.md

@@ -0,0 +1,83 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+The build is failing after the last merge.
+```
+
+Expected result:
+
+- classify the issue
+- reproduce the failure
+- narrow to root cause
+- fix and verify
+
+Sample completed output:
+
+```
+Goal/Result: Build failure debugged and fixed.
+
+Key Details:
+  Classification: [Build failure] in auth module: missing import after merge
+
+  Root cause: src/auth/index.ts:15 — import references
+  `refreshToken` from ./providers but the function was renamed to
+  `refreshAccessToken` in PR #142 (merged 2h ago).
+
+  Fix applied: Updated import in src/auth/index.ts:15
+    - Before: import { refreshToken } from './providers'
+    - After: import { refreshAccessToken } from './providers'
+
+  Verification:
+    - npm run build — PASS
+    - npm test — PASS (42/42)
+
+  Learning: Rename refactors should use project-wide find-replace.
+  This pattern has caused 3 build failures in the last month.
+
+Next Action: commit — fix is verified and ready.
+```
+
+## Example 2
+
+User request:
+
+```text
+Tests are flaky — sometimes pass, sometimes fail.
+```
+
+Expected result:
+
+- reproduce intermittent failure
+- identify shared state or race condition
+- fix and verify stability
+
+Sample completed output:
+
+```
+Goal/Result: Flaky test diagnosed and fixed.
+
+Key Details:
+  Classification: [Test failure] in user service: intermittent assertion
+  failure on test ordering
+
+  Reproduction: Ran 5 times — failed 2/5. Failures occur when
+  "create user" test runs before "list users" test.
+
+  Root cause: tests/user.test.ts:45 — tests share a database
+  connection without cleanup. "list users" test returns results
+  from "create user" test when run order is alphabetical.
+
+  Fix applied: Added beforeEach() cleanup hook to reset test
+  database state between tests.
+
+  Verification: Ran 10 times — 10/10 PASS.
+
+  Learning captured: Test isolation pattern — always clean up
+  shared state in beforeEach, not afterAll.
+
+Next Action: commit
+```

package/skills/debug/meta.yaml

@@ -0,0 +1,38 @@
+name: debug
+version: 0.2.0
+category: troubleshooting
+summary: 4-phase systematic debugging with root cause investigation, multi-component diagnostics, and 3+ fix escalation.
+summary_vi: "Gỡ lỗi hệ thống 4 giai đoạn với điều tra nguyên nhân gốc, chẩn đoán đa thành phần, và leo thang khi 3+ lần sửa thất bại."
+triggers:
+  - debug this error
+  - fix this failure
+  - why is this failing
+  - diagnose this issue
+  - investigate this error
+  - debug this regression
+  - failing test or production issue
+inputs:
+  - error message or stack trace
+  - failing command
+  - bug report or reproduction steps
+  - optional task context
+outputs:
+  - classification
+  - root cause with file:line
+  - verified fix
+  - fix attempt count
+  - learning captured
+constraints:
+  - no fixes without root cause investigation first
+  - must reproduce before diagnosing
+  - must verify fix before declaring success
+  - escalate at 3+ failed fix attempts
+related_skills:
+  - using-skills
+  - planning
+  - feature-delivery
+  - extract
+  - code-review
+  - commit
+  - verification-before-completion
+  - test-driven-development

package/skills/debug/references/output-template.md

@@ -0,0 +1,16 @@
+## Goal/Result
+
+- What was debugged:
+- Fix status:
+
+## Key Details
+
+- Classification:
+- Root cause:
+- Fix applied:
+- Verification result:
+- Learning captured:
+
+## Next Action
+
+- Recommended follow-up:

package/skills/docs-writer/SKILL.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Keep documentation aligned with how the system actually works.
+Keep documentation aligned with how the system actually works. Support both full document creation and targeted section editing.
 
 ## When To Use
 
@@ -13,22 +13,83 @@ Load this skill when writing or updating:
 - runbooks
 - API usage notes
 - project operating instructions
+- architecture diagrams
+- any documentation that should stay in sync with code
 
 ## Workflow
 
 1. Confirm the target audience and document purpose.
 2. Verify current behavior from source, commands, or config before writing.
-3. Update only the sections that need to change.
-4. Prefer concise instructions, examples, and commands over long prose.
-5. Call out assumptions or areas that still need verification.
+3. Determine scope: full document or section edit.
+4. For section edits, update only the sections that need to change — do not rewrite the entire document.
+5. Prefer concise instructions, examples, and commands over long prose.
+6. Use diagrams (mermaid) for complex flows or architecture.
+7. Call out assumptions or areas that still need verification.
+
+## Section Editing
+
+For targeted updates, prefer editing specific sections rather than rewriting the full document:
+
+1. Identify which section(s) need updating.
+2. Read the current section content.
+3. Update only the affected section while preserving surrounding structure.
+4. Verify the update does not break references or flow.
+
+This is more efficient and less error-prone than full document rewrites.
+
+## Mermaid Diagrams
+
+Use mermaid diagrams for:
+- Architecture diagrams
+- Flowcharts
+- Sequence diagrams
+- Entity relationships
+- Decision trees
+
+````markdown
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+````markdown
+```mermaid
+sequenceDiagram
+    Client->>Server: Request
+    Server->>DB: Query
+    DB-->>Server: Result
+    Server-->>Client: Response
+```
+````
+
+Diagrams render in GitHub, most doc platforms, and many editor previews. Use them when a text description would be confusing.
 
 ## Output Format
 
-- target document
-- audience
-- what changed
-- source of truth used
-- assumptions or follow-ups
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what document was created, updated, or inspected
+2. **Key Details:**
+   - target document and audience
+   - what changed (or what was created)
+   - source of truth used for verification
+   - whether section edit or full rewrite
+   - assumptions or follow-ups
+3. **Next Action** — only when a natural follow-up exists:
+   - if doc reveals code issues → `debug`
+   - if doc is part of feature work → `verification-before-completion`
+
+## Documentation Rules
+
+- Verify against actual source before writing.
+- Prefer section edits over full rewrites.
+- Use mermaid for complex flows.
+- Keep instructions concise with examples and commands.
+- Remove stale commands, paths, and references.
+- Do not mix user instructions with internal implementation details unnecessarily.
 
 ## Red Flags
 
@@ -36,7 +97,21 @@ Load this skill when writing or updating:
 - writing broad architecture claims without source verification
 - mixing user instructions with internal implementation details unnecessarily
 - leaving stale commands or paths in place
+- rewriting an entire document when only one section needed updating
+- creating near-duplicate docs instead of updating existing ones
+- leaving broken cross-references after an edit
+
+## Checklist
+
+- [ ] Target audience confirmed
+- [ ] Current behavior verified from source
+- [ ] Scope determined (section edit vs full document)
+- [ ] Content written with concise examples
+- [ ] Mermaid diagrams used where helpful
+- [ ] Stale content removed or corrected
+- [ ] Cross-references checked
+- [ ] Source of truth documented
 
 ## Done Criteria
 
-This skill is complete when the updated document has been verified against the actual source, all stale commands or paths have been corrected or removed, and the "Verification" field in the output names the specific files or commands that were checked.
+This skill is complete when the updated document has been verified against the actual source, all stale commands or paths have been corrected or removed, and the output names the specific files or commands that were checked.

package/skills/docs-writer/meta.yaml

@@ -1,22 +1,26 @@
 name: docs-writer
-version: 0.1.0
+version: 0.2.0
 category: documentation
-summary: Update documentation from verified source behavior so the docs stay useful and current.
-summary_vi: Cập nhật tài liệu từ hành vi nguồn đã xác minh để docs luôn hữu ích và cập nhật.
+summary: Write and update documentation aligned with actual code, with section editing and mermaid diagram support.
+summary_vi: "Vi\u1EBFt v\xE0 c\u1EADp nh\u1EADt t\xE0i li\u1EC7u theo code th\u1EF1c t\u1EBF, h\u1ED7 tr\u1EE3 ch\u1EC9nh s\u1EEDa t\u1EEBng ph\u1EA7n v\xE0 s\u01A1 \u0111\u1ED3 mermaid."
 triggers:
+  - write documentation
   - update the README
-  - write onboarding docs
-  - refresh runbook or API notes
+  - document this feature
+  - create a runbook
 inputs:
-  - current code or behavior
-  - existing documentation
+  - target document
+  - audience
+  - source of truth (code, commands, config)
 outputs:
-  - updated docs
-  - assumptions and verification notes
+  - created or updated document
+  - verification source noted
+  - assumptions or follow-ups
 constraints:
-  - prefer source-verified statements
-  - keep links repository-relative when possible
+  - verify against actual source before writing
+  - prefer section edits over full rewrites
 related_skills:
   - using-skills
   - repo-onboarding
-  - code-review
+  - feature-delivery
+  - verification-before-completion