@anionzo/skill 1.4.0 → 1.7.0

package/skills/code-review/SKILL.md

@@ -2,40 +2,235 @@
 
 ## Purpose
 
-Review code changes with a risk-first mindset.
+Review code changes with a risk-first, multi-perspective approach using severity-based triage. When receiving review feedback, evaluate technically before implementing.
+
+This skill covers both sides of code review: giving reviews (severity triage, multi-perspective) and receiving reviews (technical evaluation, no performative agreement).
 
 ## When To Use
 
-Load this skill when the user asks for a review of a diff, PR, commit range, or changed files.
+Load this skill when:
+
+- the user asks for a review of a diff, PR, commit range, or changed files
+- you are receiving code review feedback and need to evaluate and respond to it
+- the user says "review this", "check this code", or "fix the review comments"
+
+## Part 1: Giving Code Reviews
+
+### Workflow
+
+1. Gather the full set of changes to review.
+2. Review from four perspectives: code quality, architecture, security, completeness.
+3. Triage each finding by severity (P1/P2/P3).
+4. Present findings grouped by severity.
+5. Gate the commit on P1 findings.
+
+### Multi-Perspective Review
+
+#### Code Quality
+- Readability and simplicity
+- Duplicated logic (DRY)
+- Error handling — missing or swallowed errors
+- Type safety — `any`, unsafe casts, missing types
+- Naming — unclear variable/function names
+
+#### Architecture
+- Separation of concerns — business logic in wrong layer
+- Coupling — tight dependencies between unrelated modules
+- API design — consistent patterns, proper methods/status codes
+- File organization — follows project conventions
+
+#### Security
+- Input validation — user input sanitized
+- Auth — proper authorization checks
+- Secrets — no hardcoded credentials or tokens
+- Data exposure — sensitive data in logs, responses, or error messages
+
+#### Completeness
+- Missing tests for new logic
+- Edge cases not handled
+- Integration gaps — new code not wired into existing flows
+- Stubs or TODOs left in code
+
+### Severity Triage
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **P1** | Security vuln, data corruption, breaking change, stub shipped | **Blocks commit — must fix** |
+| **P2** | Performance issue, architecture concern, missing test | Should fix before commit |
+| **P3** | Minor cleanup, naming, style | Record for later |
+
+**Calibration:** Not everything is P1. Severity inflation wastes time. When in doubt, P2.
+
+### Handling Review Results
+
+**P1 findings exist — HARD GATE:**
+
+Do NOT proceed to commit. Do NOT offer to skip P1.
+
+> P1 findings block commit. Fix these first, then re-review.
+
+**Only P2/P3:**
+
+> No blocking issues. P2 findings recommended.
+> Options: fix P2s now, commit as-is, or create follow-up task for P2s.
+
+**Clean:**
+
+> Review passed. No issues found. Ready to commit.
+
+## Part 2: Receiving Code Reviews
+
+### Response Protocol
+
+When receiving code review feedback:
+
+1. **READ** — complete feedback without reacting
+2. **UNDERSTAND** — restate the requirement in your own words (or ask)
+3. **VERIFY** — check against codebase reality
+4. **EVALUATE** — technically sound for THIS codebase?
+5. **RESPOND** — technical acknowledgment or reasoned pushback
+6. **IMPLEMENT** — one item at a time, test each
+
+### No Performative Agreement
+
+Do not respond to review feedback with:
 
-## Workflow
+- "You're absolutely right!"
+- "Great point!" / "Excellent feedback!"
+- "Thanks for catching that!"
 
-1. Inspect the full set of relevant changes.
-2. Identify behavior changes and impacted code paths.
-3. Look for:
-   - correctness bugs
-   - regressions
-   - missing validation or edge-case handling
-   - missing or misleading tests
-4. Return findings ordered by severity, with file references.
-5. Keep summaries brief and put them after the findings.
+Instead:
+
+- Restate the technical requirement
+- Ask clarifying questions if unclear
+- Push back with technical reasoning if the suggestion is wrong
+- Just fix it — actions speak louder than words
+
+When acknowledging correct feedback:
+
+- "Fixed. [Brief description of what changed]"
+- "Good catch — [specific issue]. Fixed in [location]."
+- Or just fix it and show the code change.
+
+### When to Push Back
+
+Push back when:
+
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature being "properly implemented")
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with prior architectural decisions
+
+How to push back:
+
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests or code
+- Escalate to the user if it is an architectural disagreement
+
+### YAGNI Check for Suggested Features
+
+When a reviewer suggests "implementing properly" or adding capabilities:
+
+1. Search the codebase for actual usage of the component in question
+2. If unused: suggest removing it (YAGNI)
+3. If used: then implement the improvement
+
+### Handling Unclear Feedback
+
+If any review item is unclear, STOP — do not implement anything yet. Ask for clarification on all unclear items before proceeding. Items may be related, and partial understanding leads to wrong implementation.
+
+### Implementation Order for Multi-Item Feedback
+
+1. Clarify anything unclear FIRST
+2. Then implement in this order:
+   - Blocking issues (breaks, security)
+   - Simple fixes (typos, imports)
+   - Complex fixes (refactoring, logic)
+3. Test each fix individually
+4. Verify no regressions
 
 ## Output Format
 
-- findings first, ordered by severity
-- file and line references when available
-- open questions or assumptions
-- short summary or residual risk note
+Present results using the Shared Output Contract:
+
+**When giving a review:**
+
+1. **Goal/Result** — review verdict: PASS, BLOCKED (P1 exists), or PASS with warnings
+2. **Key Details:**
+   ```
+   P1 (blocks commit): X findings
+   - [file:line] Description — why it is critical
+
+   P2 (should fix): X findings
+   - [file:line] Description — impact
+
+   P3 (nice to have): X findings
+   - [file:line] Description
+
+   Verdict: PASS / BLOCKED
+   ```
+3. **Next Action:**
+   - if P1 exists → fix these first, then re-review
+   - if only P2/P3 → `commit` (or fix P2s first)
+   - if clean → `commit`
+
+**When receiving a review:**
+
+1. **Goal/Result** — review feedback evaluated and implementation status
+2. **Key Details:**
+   - items understood vs. items needing clarification
+   - items implemented with verification
+   - items pushed back with reasoning
+3. **Next Action:**
+   - all items resolved → `verification-before-completion`
+   - items remain unclear → waiting for clarification
 
 ## Red Flags
 
+**When giving reviews:**
 - reviewing only the latest file and ignoring related changes
 - focusing on style before correctness
 - vague comments with no user-visible impact
-- claiming safety without considering missing tests or migration risk
+- severity inflation — calling everything P1
+- approving code with P1 findings
+- not checking the actual diff (reviewing from memory)
+- skipping the security perspective
+
+**When receiving reviews:**
+- performative agreement ("Great point!")
+- implementing suggestions without verifying against codebase
+- implementing all items without testing each one
+- avoiding pushback when the suggestion is technically wrong
+- implementing unclear items based on assumptions
+- thanking the reviewer instead of just fixing the issue
+
+## Checklist
+
+**Giving a review:**
+- [ ] Full diff reviewed
+- [ ] Code quality perspective checked
+- [ ] Architecture perspective checked
+- [ ] Security perspective checked
+- [ ] Completeness perspective checked
+- [ ] Findings triaged by severity (P1/P2/P3)
+- [ ] P1 findings block commit (hard gate)
+- [ ] File and line references included where possible
+- [ ] Next step communicated
+
+**Receiving a review:**
+- [ ] All feedback read completely
+- [ ] Each item understood or clarification requested
+- [ ] Suggestions verified against codebase before implementing
+- [ ] Push back applied where technically warranted
+- [ ] Items implemented one at a time
+- [ ] Each fix tested individually
+- [ ] No performative agreement used
 
 ## Done Criteria
 
-This skill is complete when every finding includes a severity, a file and line reference where possible, and a plain-language statement of user-visible impact. The residual risk field must be populated even if no blocking issues were found.
+**Giving:** Every finding includes a severity, a file and line reference where possible, and a plain-language statement of user-visible impact. The verdict is clearly stated as PASS or BLOCKED.
 
-If blocking issues are found, hand off to `bug-triage` or `planning` before the change proceeds.
+**Receiving:** All review items are either implemented with individual verification, pushed back with technical reasoning, or waiting on clarification. No performative agreement was used.

package/skills/code-review/meta.yaml

@@ -1,24 +1,36 @@
 name: code-review
-version: 0.1.0
+version: 0.3.0
 category: review
-summary: Review changes for bugs, regressions, and missing tests before style or polish comments.
-summary_vi: Review thay đổi tìm bug, regression, và test thiếu trước khi comment về style hoặc polish.
+summary: Multi-perspective code review with P1/P2/P3 severity triage, plus technical evaluation protocol for receiving feedback.
+summary_vi: "Review code đa chiều với P1/P2/P3, cộng protocol đánh giá kỹ thuật khi nhận feedback."
 triggers:
   - review this PR
   - review these changes
   - look for risks before merge
+  - check this code
+  - fix review comments
+  - respond to review feedback
 inputs:
   - diff or changed files
+  - review feedback to evaluate
   - relevant tests or docs when needed
+  - optional task or spec reference
 outputs:
-  - severity-ranked findings
-  - open questions
-  - residual risk notes
+  - severity-ranked findings (P1/P2/P3)
+  - review verdict (PASS/BLOCKED)
+  - technical evaluation of received feedback
+  - items implemented or pushed back
 constraints:
-  - findings first
-  - avoid style-only comments unless they hide a real risk
+  - P1 blocks commit (hard gate)
+  - no performative agreement when receiving feedback
+  - verify suggestions against codebase before implementing
+  - push back with technical reasoning when warranted
 related_skills:
   - using-skills
-  - bug-triage
+  - debug
+  - feature-delivery
+  - refactor-safe
   - verification-before-completion
+  - commit
   - planning
+  - test-driven-development

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,29 @@
+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

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: