@anionzo/skill 1.3.0 → 1.6.0

package/skills/brainstorming/SKILL.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Refine a fuzzy request into a concrete direction that is clear enough to plan.
+Refine a fuzzy request into a concrete direction, and when needed, lock decisions into a specification before implementation begins.
+
+This skill combines idea exploration with spec-driven development: first clarify what to build, then optionally formalize it into a spec with locked decisions and acceptance criteria.
 
 ## When To Use
 
@@ -11,35 +13,196 @@ Load this skill when:
 - the user has an idea but not a settled approach
 - the scope or success criteria are still unclear
 - multiple reasonable options exist and the tradeoff matters
-- starting implementation immediately would force too many assumptions
+- the user says "spec this", "define requirements", or "what should we build"
+- planning a non-trivial feature that has ambiguous requirements
+- multiple stakeholders need to agree on behavior before code is written
 
 Skip this skill and go directly to `planning` when the request is already specific: a named feature with clear scope, a known code path, or an explicit task with acceptance criteria.
 
-## Workflow
+## Workflow Overview
+
+**Phase 0: Explore** — clarify the idea, surface tradeoffs, extract decisions
+**Phase 1: Lock Direction** — lock the recommended direction and scope boundary
+**Phase 2: Write Spec** (optional) — formalize into a spec document with ACs
+**Phase 3: Review** — get user approval before handoff
+
+For simple clarifications, Phase 0 + Phase 1 is sufficient. For non-trivial features, continue through Phase 2 + Phase 3.
+
+## Phase 0: Explore
+
+### 0.1 Scope Assessment
+
+Assess the request complexity:
+
+- **Quick** — bounded, low ambiguity (rename a flag, tweak a label). Clarify and hand off to `planning`.
+- **Standard** — normal feature with decisions to extract. Run full exploration.
+- **Deep** — cross-cutting, strategic, or highly ambiguous. Run exploration with extra depth, then write a spec.
+
+### 0.2 Restate and Question
 
 1. Restate the request in plain language.
 2. Ask focused questions that reduce ambiguity quickly.
 3. Surface the most important tradeoffs, not every possible one.
-4. Propose one or two viable directions with clear consequences.
-5. Lock the current best direction, scope boundary, and open questions.
-6. End with a handoff into `planning` when the request is concrete enough.
+
+**HARD RULE: Ask ONE question at a time. Wait for the user's response before asking the next.**
+
+Rules:
+
+- One question per message — never bundled
+- Single-select multiple choice preferred over open-ended
+- Start broad (what/why/for whom) then narrow (constraints, edge cases)
+- 3-4 questions per topic area, then checkpoint:
+  > "More questions about [area], or move on? (Remaining: [unvisited areas])"
+
+### 0.3 Gray Area Identification
+
+Generate 2-4 gray areas — decisions that affect implementation but were not stated in the request. A gray area is a decision that would force the planner to make an assumption without it.
+
+Quick codebase scout (grep, not deep analysis):
+
+- check what already exists that is related
+- annotate options with what the codebase already has
+
+Filter OUT:
+
+- technical implementation details (architecture, library choices) — that is `planning`'s job
+- performance concerns
+- scope expansion (new capabilities not requested)
+
+### 0.4 Decision Locking
+
+After each gray area is resolved, lock the decision:
+
+> "Lock decision D[N]: [summary]. Confirmed?"
+
+Assign stable IDs: D1, D2, D3... These IDs carry forward into the spec.
+
+**Scope creep response** — when the user suggests something outside scope:
+
+> "[Feature X] is a new capability — noted as a separate work item. Back to [current area]: [question]"
+
+## Phase 1: Lock Direction
+
+Summarize the exploration output. All three of the following must be written down explicitly:
+
+1. **Recommended direction** — the approach to take
+2. **At least one key constraint** — what limits or shapes the solution
+3. **Scope boundary** — what is in and what is out
+
+Present viable options with consequences if multiple exist, but recommend one.
+
+**For quick scope:** This is the final output. Hand off to `planning`.
+
+**For standard/deep scope:** Continue to Phase 2.
+
+## Phase 2: Write Spec (For Standard/Deep Scope)
+
+### Spec Document Structure
+
+```markdown
+## Overview
+
+Brief description of the feature and its purpose.
+
+## Locked Decisions
+
+- D1: [Decision summary]
+- D2: [Decision summary]
+
+## Requirements
+
+### Functional Requirements
+- FR-1: [Requirement description]
+- FR-2: [Requirement description]
+
+### Non-Functional Requirements
+- NFR-1: [Performance, security, etc.]
+
+## Acceptance Criteria
+
+- [ ] AC-1: [Testable criterion]
+- [ ] AC-2: [Testable criterion]
+
+## Scenarios
+
+### Scenario 1: [Happy Path]
+**Given** [context]
+**When** [action]
+**Then** [expected result]
+
+### Scenario 2: [Edge Case]
+**Given** [context]
+**When** [action]
+**Then** [expected result]
+
+## Open Questions
+
+- [ ] Question 1?
+```
+
+### Spec Quality Rules
+
+- Requirements must be testable.
+- Acceptance criteria must be observable outcomes, not vague goals.
+- Scenarios should cover the happy path plus important edge cases.
+- Open questions must stay explicit, not buried in prose.
+- Keep the spec focused on WHAT, not HOW (implementation is `planning`'s job).
+
+## Phase 3: Review
+
+Present the spec (or the locked direction for quick scope) and ask:
+
+> Please review:
+> - **Approve** if complete
+> - **Edit** if you want to modify something
+> - **Add more** if requirements are missing
+
+Handle the response:
+
+- **Approved** → hand off to next skill
+- **Edit requested** → update, return to review
+- **Add more** → gather additional requirements, update, return to review
 
 ## Output Format
 
-- clarified goal
-- constraints and assumptions
-- viable options considered
-- recommended direction
-- unresolved questions
-- next skill to invoke
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the clarified direction, spec (if written), and approval status
+2. **Key Details:**
+   - locked decisions (D1, D2...)
+   - scope boundary (in/out)
+   - viable options considered with tradeoffs
+   - acceptance criteria (if spec written)
+   - open questions
+3. **Next Action** — after approval:
+   - to review each step: `planning` (with spec reference)
+   - to execute everything at once: `go-pipeline` (with spec reference)
+   - if requirements still unclear: state what decision is still needed
 
 ## Red Flags
 
 - diving into file-level implementation too early
 - asking many questions that do not change the decision
+- batching multiple questions in one message (HARD RULE violation)
 - presenting vague options with no tradeoff explanation
 - pretending the problem is settled when key constraints are still unknown
+- creating a spec without user input
+- answering your own questions during exploration
+- skipping the review step
+- writing implementation notes instead of requirements
+- leaving ambiguous acceptance criteria that cannot be verified
+
+## Checklist
+
+- [ ] Scope assessed (quick/standard/deep)
+- [ ] Request restated in plain language
+- [ ] Gray areas identified and explored (one question at a time)
+- [ ] Decisions locked with stable IDs (D1, D2...)
+- [ ] Direction, constraint, and scope boundary documented
+- [ ] Spec written (if standard/deep scope): overview, decisions, requirements, ACs, scenarios
+- [ ] User reviewed and approved
+- [ ] Next step communicated
 
 ## Done Criteria
 
-This skill is complete when all three of the following are written down explicitly: the recommended direction, at least one key constraint, and the scope boundary. At that point, `planning` can proceed without inventing missing requirements.
+This skill is complete when the recommended direction, at least one key constraint, and the scope boundary are all written down explicitly. For standard/deep scope, the spec must be approved with acceptance criteria defined. If the spec is not approved, the skill is complete when the user has the information needed to make a decision.

package/skills/brainstorming/meta.yaml

@@ -1,23 +1,32 @@
 name: brainstorming
-version: 0.1.0
+version: 0.2.0
 category: discovery
-summary: Turn a rough idea or underspecified request into a concrete, reviewable direction before planning begins.
-summary_vi: Biến ý tưởng thô hoặc request chưa rõ thành hướng đi cụ thể, có thể review, trước khi bắt đầu lập plan.
+summary: Turn a rough idea into a concrete direction with locked decisions, optionally formalized into a spec with acceptance criteria.
+summary_vi: "Biến ý tưởng thô thành hướng đi cụ thể với quyết định đã khóa, có thể formalize thành spec với acceptance criteria."
 triggers:
   - help me think this through
   - explore the approach first
   - the request is vague or underspecified
+  - spec this feature
+  - define requirements
+  - what should we build
+  - create a specification
 inputs:
-  - rough idea
+  - rough idea or feature description
   - user goals and constraints
 outputs:
-  - clarified goal
-  - key decisions
-  - open questions
-  - handoff into planning
+  - clarified goal and direction
+  - locked decisions (D1, D2...)
+  - scope boundary
+  - optional spec with requirements and ACs
+  - approval status
 constraints:
-  - avoid jumping into code or low-level implementation too early
-  - keep the discussion concrete and decision-oriented
+  - ask one question at a time during exploration
+  - do not skip the review step
+  - keep focused on WHAT not HOW
 related_skills:
   - using-skills
   - planning
+  - research
+  - go-pipeline
+  - feature-delivery

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