@anionzo/skill 1.3.0 → 1.6.0

package/skills/commit/SKILL.md

@@ -0,0 +1,187 @@
+# Commit
+
+## Purpose
+
+Create clean, well-scoped commits by learning the repo's commit style first, then proposing a message for user approval.
+
+This skill ensures that every commit is intentional, matches the project's existing conventions, and is never created without explicit user permission.
+
+## The Iron Rule
+
+```
+NEVER COMMIT WITHOUT EXPLICIT USER APPROVAL
+```
+
+No exceptions. Not even when the user says "commit this" — still show the proposed message and wait for confirmation. The only exception is when the user explicitly grants blanket permission (e.g., "commit freely", "auto-commit is fine").
+
+## When To Use
+
+Load this skill when:
+
+- ready to commit completed work
+- the user says "commit this", "save my changes", or "commit"
+- finishing a task and need to record the change properly
+- multiple unrelated changes are staged and need to be split
+
+## Workflow
+
+1. Read the repo's recent commit history to learn the style.
+2. Review what is staged.
+3. Verify the staged changes are coherent (single concern).
+4. Generate a commit message that matches the repo's style.
+5. Present the commit for user approval.
+6. Commit ONLY after explicit approval.
+
+## Step 1: Learn the Repo's Commit Style
+
+**Before proposing any commit message, study the existing history:**
+
+```bash
+git log --oneline -20
+```
+
+Look for:
+
+- **Format pattern** — does the repo use conventional commits (`feat:`, `fix:`), plain messages, ticket prefixes (`JIRA-123:`), or something else?
+- **Casing** — lowercase subjects? Sentence case? All caps type prefix?
+- **Scope usage** — does the repo use `feat(auth):` or just `feat:`?
+- **Subject length** — typical length of subject lines?
+- **Body style** — do commits have bodies? What do they explain?
+- **Language** — English? Vietnamese? Mixed?
+
+**Match the observed pattern.** Do not impose a different convention on a repo that already has one.
+
+If the repo has no clear pattern (new repo, mixed styles), fall back to conventional commits:
+
+```
+<type>(<scope>): <subject>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `build`, `ci`
+
+## Step 2: Review Staged Changes
+
+```bash
+git status
+git diff --staged
+```
+
+Check:
+
+- Are the right files staged?
+- Is anything missing that should be included?
+- Is anything staged that should not be (secrets, generated files, unrelated changes)?
+
+## Step 3: Verify Coherence
+
+A good commit addresses ONE concern. If the staged diff mixes unrelated work:
+
+> These changes span multiple concerns:
+> - Feature X changes in `src/feature/`
+> - Bug fix in `src/utils/`
+>
+> Recommend splitting into separate commits. Stage one concern at a time.
+
+Do NOT commit mixed changes without calling it out.
+
+## Step 4: Generate Commit Message
+
+Based on the style learned in Step 1, generate a commit message that:
+
+- Matches the repo's existing format and conventions
+- Has a subject that explains the WHY or the user-visible change
+- Has a body that explains reasoning (not a diff summary) when the change is non-trivial
+- References task/issue IDs when applicable
+- Does not include "Co-Authored-By" unless the user requests it
+- Does not include "Generated with AI" or similar attribution
+
+## Step 5: Present for Approval
+
+```
+Repo commit style observed: conventional commits, lowercase, with scope
+Recent examples:
+  feat: add 6 new skills and upgrade 4 existing skills
+  fix(auth): handle expired refresh tokens
+
+Proposed commit:
+
+  feat(planning): add bite-sized task granularity and no-placeholder rule
+
+Staged files:
+  M skills/planning/SKILL.md
+  M skills/planning/meta.yaml
+
+Proceed? (yes / edit message / no)
+```
+
+**WAIT for the user's response.** Do NOT proceed until you receive one of:
+
+- **yes / ok / go / ship it** → commit
+- **edit** → user provides a new message or adjustments
+- **no** → abort, explain what to do next
+
+## Step 6: Commit
+
+Only after explicit approval:
+
+```bash
+git commit -m "<approved-message>"
+```
+
+## Output Format
+
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — whether a commit was proposed, created, or blocked
+2. **Key Details:**
+   - observed repo commit style
+   - the proposed or final commit message
+   - staged files summary
+   - any concerns about the diff (mixed concerns, missing files)
+   - approval status
+3. **Next Action** — only when a natural follow-up exists:
+   - after successful commit → `verification-before-completion` or `extract`
+   - if commit blocked → explain what to fix first
+
+## Commit Rules
+
+- **NEVER auto-commit without user approval** — this is the most important rule
+- Only commit staged files
+- No "Co-Authored-By" lines unless the user requests it
+- No "Generated with AI" or similar attribution lines
+- If nothing is staged, say so and stop
+- Learn the repo style before proposing — do not impose a foreign convention
+
+## Red Flags
+
+- committing without reviewing the diff
+- committing without reading the repo's commit history first
+- proposing a commit style that does not match the repo's existing convention
+- mixing unrelated changes in one commit
+- writing commit messages that describe the diff instead of the intent
+- auto-committing without user approval
+- committing with failing tests or lint errors still present
+- assuming "commit this" means "commit without showing me"
+
+## Checklist
+
+- [ ] Repo commit history read (git log)
+- [ ] Commit style identified and matched
+- [ ] Staged changes reviewed
+- [ ] Changes are coherent (single concern)
+- [ ] Commit message follows repo's convention
+- [ ] Subject explains why/what changed (not a diff summary)
+- [ ] Commit message presented to user
+- [ ] User explicitly approved
+- [ ] Commit created successfully
+
+## Abort Conditions
+
+- Nothing staged
+- Staged diff includes unrelated work that should be split
+- User has not explicitly approved the final message
+- Secrets or credentials detected in staged files
+
+## Done Criteria
+
+This skill is complete when the commit is created with explicit user approval, or when the user is informed why the commit was blocked and what to do about it. A commit created without user approval is a skill failure, regardless of whether the message was correct.

package/skills/commit/examples.md

@@ -0,0 +1,62 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Commit my changes.
+```
+
+Expected result:
+
+- review staged changes
+- check coherence (single concern)
+- generate conventional commit message
+- present for approval
+
+Sample completed output:
+
+```
+Goal/Result: Commit proposed — awaiting approval.
+
+Key Details:
+  Ready to commit:
+
+  feat(auth): add JWT token refresh endpoint
+
+  - Adds /auth/refresh route for issuing new access tokens
+  - Preserves existing sessions during refresh
+
+  Staged files:
+    M src/routes/auth.ts
+    A src/middleware/refresh.ts
+    M tests/auth.test.ts
+
+  Proceed? (yes / no / edit)
+```
+
+## Example 2
+
+User request:
+
+```text
+Save my work.
+```
+
+Expected result — mixed changes detected:
+
+```
+Goal/Result: Commit blocked — staged changes span multiple concerns.
+
+Key Details:
+  These changes span multiple concerns:
+  - Feature: new search endpoint in src/routes/search.ts
+  - Bug fix: null check in src/utils/format.ts
+  - Style: whitespace cleanup in src/app.ts
+
+  Recommend splitting into separate commits.
+  Stage one concern at a time.
+
+Next Action: Stage the feature changes first, then commit each concern separately.
+```

package/skills/commit/meta.yaml

@@ -0,0 +1,30 @@
+name: commit
+version: 0.2.0
+category: workflow
+summary: Learn repo commit style from history, propose a matching message, and commit ONLY after explicit user approval.
+summary_vi: "Học style commit từ history, đề xuất message phù hợp, và commit CHỈ KHI user xác nhận rõ ràng."
+triggers:
+  - commit these changes
+  - save my work
+  - ready to commit
+inputs:
+  - staged git changes
+  - repo commit history (read automatically)
+  - optional task or issue reference
+outputs:
+  - observed commit style
+  - proposed commit message matching repo convention
+  - user approval gate
+  - committed changes
+constraints:
+  - NEVER auto-commit without explicit user approval
+  - read commit history before proposing a message
+  - match the repo's existing commit convention
+  - one concern per commit
+related_skills:
+  - using-skills
+  - verification-before-completion
+  - code-review
+  - debug
+  - extract
+  - go-pipeline

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

@@ -0,0 +1,14 @@
+## Goal/Result
+
+- Commit status:
+
+## Key Details
+
+- Commit message:
+- Staged files:
+- Diff concerns:
+- Approval status:
+
+## Next Action
+
+- Recommended follow-up:

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: