mirror of
https://github.com/rohitg00/skillkit.git
synced 2026-11-18 18:04:26 +00:00
optimize 14 skills via tessl review (avg 24% → 92%) (#81)
Ran `npx tessl skill review --optimize` on all methodology pack skills and find-skills. Key improvements: - Better descriptions with "Use when..." clauses and concrete verbs - Lowercase-hyphenated name format for consistency - Trimmed self-evident prose Claude already understands - Added executable examples and quick reference tables - Condensed verbose sections into compact tables/summaries - Fixed YAML parsing errors (unquoted colons in descriptions) Net result: -552 lines across 14 files.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Handoff Protocols
|
||||
description: Effectively transfer work context between team members or agents
|
||||
name: handoff-protocols
|
||||
description: Manages work transitions between team members or agents by creating structured handoff documents, summarizing project status, documenting key decisions, blockers, and open questions, and generating onboarding briefs. Use when someone needs to hand off, hand over, or transition a project; pass work to another person or agent; brief a colleague taking over; prepare a shift change summary; or onboard someone mid-task. Produces ready-to-use handoff documents covering current status, next steps, known issues, technical context, and communication templates for both planned and unplanned transfers.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- handoff
|
||||
@@ -23,39 +23,15 @@ relatedSkills:
|
||||
|
||||
# Handoff Protocols
|
||||
|
||||
You are executing a work handoff between team members or agents. A good handoff ensures context is preserved and work continues smoothly without loss of information.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**The recipient should be able to continue work immediately without asking "what were you doing?"**
|
||||
|
||||
A complete handoff transfers not just the work, but the context, decisions, and reasoning.
|
||||
You are executing a work handoff between team members or agents.
|
||||
|
||||
## Handoff Types
|
||||
|
||||
### Type 1: Planned Handoff
|
||||
|
||||
Scheduled transfer (end of shift, vacation, role change):
|
||||
|
||||
- Time to prepare comprehensive documentation
|
||||
- Opportunity for sync meeting
|
||||
- Can do gradual transition
|
||||
|
||||
### Type 2: Unplanned Handoff
|
||||
|
||||
Unexpected transfer (illness, emergency, priority change):
|
||||
|
||||
- Limited preparation time
|
||||
- Rely on existing documentation
|
||||
- May need to reconstruct context
|
||||
|
||||
### Type 3: Partial Handoff
|
||||
|
||||
Transfer specific piece while retaining some work:
|
||||
|
||||
- Clear boundary definition
|
||||
- Shared ownership considerations
|
||||
- Integration points defined
|
||||
| Type | When | Key Characteristics |
|
||||
|------|------|---------------------|
|
||||
| **Planned** | End of shift, vacation, role change | Time to prepare docs; opportunity for sync meeting; gradual transition possible |
|
||||
| **Unplanned** | Illness, emergency, priority change | Limited prep time; rely on existing docs; may need to reconstruct context |
|
||||
| **Partial** | Transfer one piece while retaining other work | Requires clear boundary definition; shared ownership and integration points |
|
||||
|
||||
## Handoff Document
|
||||
|
||||
@@ -242,21 +218,7 @@ Thanks!
|
||||
|
||||
## Handoff Anti-Patterns
|
||||
|
||||
### The Brain Dump
|
||||
- **Problem:** Unstructured info dump
|
||||
- **Fix:** Use structured handoff document
|
||||
|
||||
### The Ghost
|
||||
- **Problem:** Disappear after handoff
|
||||
- **Fix:** Remain available for questions
|
||||
|
||||
### The Incomplete
|
||||
- **Problem:** Missing critical context
|
||||
- **Fix:** Use checklist, get recipient confirmation
|
||||
|
||||
### The Mess
|
||||
- **Problem:** Code in broken state
|
||||
- **Fix:** Clean up before handoff
|
||||
Avoid: brain dumps of unstructured info, disappearing after handoff, omitting critical context, and handing off code in a broken state.
|
||||
|
||||
## Receiving a Handoff
|
||||
|
||||
|
||||
+31
-108
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Parallel Investigation
|
||||
description: Coordinate multiple investigation threads for complex problems
|
||||
name: parallel-investigation
|
||||
description: Coordinates parallel investigation threads to simultaneously explore multiple hypotheses or root causes across different system areas. Use when debugging production incidents, slow API performance, multi-system integration failures, or complex bugs where the root cause is unclear and multiple plausible theories exist; when serial troubleshooting is too slow; or when multiple investigators can divide root-cause analysis work. Provides structured phases for problem decomposition, thread assignment, sync points with Continue/Pivot/Converge decisions, and final report synthesis.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- investigate in parallel
|
||||
@@ -22,28 +22,13 @@ relatedSkills:
|
||||
|
||||
# Parallel Investigation
|
||||
|
||||
You are coordinating parallel investigation threads to explore multiple hypotheses or approaches simultaneously. This is effective for complex problems where the root cause is unclear.
|
||||
Coordinate parallel investigation threads to explore multiple hypotheses simultaneously. Most effective for production incidents, performance regressions, or integration failures where the root cause is unclear.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**When uncertain, explore multiple paths in parallel. Converge when evidence points to an answer.**
|
||||
|
||||
Parallel investigation reduces time-to-solution for complex problems by eliminating serial bottlenecks.
|
||||
|
||||
## When to Use Parallel Investigation
|
||||
|
||||
Use this methodology when:
|
||||
|
||||
- Root cause is unknown with multiple plausible theories
|
||||
- Problem is complex with many interacting components
|
||||
- Time pressure requires faster resolution
|
||||
- Multiple team members are available
|
||||
- Initial investigation hasn't narrowed down the cause
|
||||
|
||||
Don't use when:
|
||||
- Problem is straightforward
|
||||
- Only one likely cause
|
||||
- Resources are constrained
|
||||
Parallel investigation reduces time-to-solution by eliminating serial bottlenecks.
|
||||
|
||||
## Investigation Structure
|
||||
|
||||
@@ -65,10 +50,7 @@ Investigation Threads:
|
||||
└── Check third-party API response times
|
||||
```
|
||||
|
||||
Each thread should be:
|
||||
- Independent (can be investigated without blocking others)
|
||||
- Focused (clear scope and success criteria)
|
||||
- Time-boxed (defined duration before sync)
|
||||
Each thread should be independent (no blocking dependencies), focused (clear scope), and time-boxed.
|
||||
|
||||
### Phase 2: Thread Assignment
|
||||
|
||||
@@ -83,22 +65,16 @@ Assign threads with clear ownership:
|
||||
- Index utilization
|
||||
- Connection pool metrics
|
||||
**Report Format:** Summary + evidence
|
||||
|
||||
## Thread B: Application Code
|
||||
**Investigator:** [Name/Agent B]
|
||||
...
|
||||
```
|
||||
|
||||
### Phase 3: Parallel Execution
|
||||
|
||||
Each thread follows this pattern:
|
||||
|
||||
```
|
||||
1. Gather evidence specific to thread scope
|
||||
2. Document findings as you go
|
||||
3. Identify if thread is leading to answer or dead end
|
||||
3. Identify if thread is a lead or dead end
|
||||
4. Prepare summary for sync point
|
||||
```
|
||||
|
||||
**Thread Log Template:**
|
||||
```markdown
|
||||
@@ -106,11 +82,10 @@ Each thread follows this pattern:
|
||||
**Start:** [Time]
|
||||
|
||||
### Findings
|
||||
- [Timestamp] [Finding 1]
|
||||
- [Timestamp] [Finding 2]
|
||||
- [Timestamp] [Finding]
|
||||
|
||||
### Evidence
|
||||
- [Screenshot/Log/Metric]
|
||||
- [Log/Metric/Screenshot]
|
||||
|
||||
### Preliminary Conclusion
|
||||
[What this thread suggests about the problem]
|
||||
@@ -122,73 +97,29 @@ Regular convergence to share findings:
|
||||
|
||||
```
|
||||
Sync Point Agenda:
|
||||
1. Thread A report (2 min)
|
||||
2. Thread B report (2 min)
|
||||
3. Thread C report (2 min)
|
||||
4. Thread D report (2 min)
|
||||
5. Discussion & correlation (5 min)
|
||||
6. Decision: Continue, pivot, or converge (3 min)
|
||||
1. Each thread report (2 min each)
|
||||
2. Discussion & correlation (5 min)
|
||||
3. Decision: Continue, Pivot, or Converge (3 min)
|
||||
```
|
||||
|
||||
**Sync Point Decisions:**
|
||||
- **Continue**: Threads are progressing, continue parallel
|
||||
- **Continue**: Threads are progressing, maintain parallel execution
|
||||
- **Pivot**: Redirect threads based on new evidence
|
||||
- **Converge**: One thread found the answer, others join
|
||||
- **Converge**: One thread found the answer, others join to validate
|
||||
|
||||
### Phase 5: Convergence
|
||||
|
||||
When a thread identifies the likely cause:
|
||||
|
||||
1. **Validate** - Other threads verify the finding
|
||||
2. **Deep dive** - Focused investigation on identified cause
|
||||
3. **Document** - Compile findings from all threads
|
||||
1. **Validate** — Other threads verify the finding
|
||||
2. **Deep dive** — Focused investigation on identified cause
|
||||
3. **Document** — Compile findings from all threads
|
||||
|
||||
## Coordination Patterns
|
||||
|
||||
### Hub and Spoke
|
||||
**Hub and Spoke**: One coordinator assigns threads, tracks progress, calls sync points, and makes convergence decisions. Best when one person has the most context.
|
||||
|
||||
One coordinator, multiple investigators:
|
||||
|
||||
```
|
||||
┌─────────┐
|
||||
│ Hub │
|
||||
│(Coord) │
|
||||
└────┬────┘
|
||||
│
|
||||
┌────────┼────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────┐┌───────┐┌───────┐
|
||||
│Thread ││Thread ││Thread │
|
||||
│ A ││ B ││ C │
|
||||
└───────┘└───────┘└───────┘
|
||||
```
|
||||
|
||||
Coordinator responsibilities:
|
||||
- Assigns threads
|
||||
- Tracks progress
|
||||
- Calls sync points
|
||||
- Makes convergence decisions
|
||||
|
||||
### Peer Network
|
||||
|
||||
Equal investigators sharing findings:
|
||||
|
||||
```
|
||||
┌───────┐ ┌───────┐
|
||||
│Thread │◄───▶│Thread │
|
||||
│ A │ │ B │
|
||||
└───┬───┘ └───┬───┘
|
||||
│ │
|
||||
▼ ▼
|
||||
◄─────────────►
|
||||
Shared
|
||||
Channel
|
||||
```
|
||||
|
||||
Each investigator:
|
||||
- Posts findings to shared channel
|
||||
- Reviews others' findings
|
||||
- Volunteers to converge when pattern emerges
|
||||
**Peer Network**: Equal investigators post findings to a shared channel and self-organize convergence when a pattern emerges. Best when investigators have similar expertise.
|
||||
|
||||
## Communication Protocol
|
||||
|
||||
@@ -209,14 +140,12 @@ Each investigator:
|
||||
|
||||
**Status:** Hot Lead
|
||||
**Key Finding:** Missing index on orders.user_id
|
||||
**Evidence:** Query taking 3.2s, explain shows table scan
|
||||
**Recommendation:** This is likely the cause, suggest converge
|
||||
**Evidence:** Query taking 3.2s, explain shows full table scan
|
||||
**Recommendation:** Likely root cause — suggest converge
|
||||
```
|
||||
|
||||
## Decision Framework
|
||||
|
||||
At each sync point:
|
||||
|
||||
| Thread Status | Action |
|
||||
|---------------|--------|
|
||||
| All exploring | Continue parallel |
|
||||
@@ -227,19 +156,17 @@ At each sync point:
|
||||
|
||||
## Time Management
|
||||
|
||||
```
|
||||
Hour 1:
|
||||
├── 0:00 - Problem decomposition
|
||||
├── 0:10 - Thread assignment
|
||||
├── 0:15 - Parallel investigation begins
|
||||
├── 0:45 - Sync point #1
|
||||
├── 0:50 - Continue/pivot/converge decision
|
||||
A typical two-hour investigation:
|
||||
|
||||
Hour 2 (if needed):
|
||||
├── 1:00 - Continue investigation
|
||||
├── 1:30 - Sync point #2
|
||||
├── 1:35 - Final convergence
|
||||
```
|
||||
0:00 Problem decomposition & thread assignment
|
||||
0:15 Parallel investigation begins
|
||||
0:45 Sync point #1 → Continue/Pivot/Converge decision
|
||||
1:30 Sync point #2 (if continuing)
|
||||
1:35 Final convergence & documentation
|
||||
```
|
||||
|
||||
Adjust sync point cadence based on incident severity — every 20 minutes for critical outages, every 45 minutes for lower-urgency investigations.
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -256,10 +183,7 @@ Hour 2 (if needed):
|
||||
### Thread A: [Area]
|
||||
- Investigator: [Name]
|
||||
- Findings: [Summary]
|
||||
- Outcome: [Lead/Dead End/Root Cause]
|
||||
|
||||
### Thread B: [Area]
|
||||
...
|
||||
- Outcome: [Lead / Dead End / Root Cause]
|
||||
|
||||
## Root Cause
|
||||
[Detailed explanation of what was found]
|
||||
@@ -273,11 +197,10 @@ Hour 2 (if needed):
|
||||
|
||||
## Lessons Learned
|
||||
- [Learning 1]
|
||||
- [Learning 2]
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **debugging/root-cause-analysis**: Each thread follows RCA principles
|
||||
- **debugging/hypothesis-testing**: Threads test specific hypotheses
|
||||
- **handoff-protocols**: When passing thread to another person
|
||||
- **handoff-protocols**: When passing a thread to another person
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Structured Code Review
|
||||
description: Multi-stage code review process for thorough and constructive feedback
|
||||
name: structured-code-review
|
||||
description: Performs a structured five-stage code review covering requirements compliance, correctness, code quality, testing, and security/performance. Each stage uses targeted checklists and categorized feedback (Blocker/Major/Minor/Nit) with actionable suggestions and rationale. Use when the user asks for code review, PR feedback, pull request review, or wants their code checked for bugs, style issues, or vulnerabilities — triggered by phrases like "review my code", "check this PR", "review my changes", "pull request review", or "code feedback".
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- code review
|
||||
@@ -36,12 +36,6 @@ A structured review catches more issues and provides better feedback than an uns
|
||||
|
||||
First, verify the code meets its requirements.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Does this implement what was requested?
|
||||
- Are all acceptance criteria met?
|
||||
- Are edge cases handled?
|
||||
- Is scope appropriate (not too little, not too much)?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Implements stated requirements
|
||||
- [ ] Handles specified edge cases
|
||||
@@ -57,12 +51,6 @@ First, verify the code meets its requirements.
|
||||
|
||||
Next, verify the code works correctly.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Is the logic correct?
|
||||
- Are there bugs or errors?
|
||||
- Are error conditions handled?
|
||||
- Is the code complete?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Logic is sound
|
||||
- [ ] No obvious bugs
|
||||
@@ -78,12 +66,6 @@ Next, verify the code works correctly.
|
||||
|
||||
Then, evaluate code quality and maintainability.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Is the code readable?
|
||||
- Does it follow conventions?
|
||||
- Is it appropriately simple?
|
||||
- Is it maintainable?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Clear naming
|
||||
- [ ] Reasonable function/method length
|
||||
@@ -100,11 +82,6 @@ Then, evaluate code quality and maintainability.
|
||||
|
||||
Evaluate test coverage and quality.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Is there adequate test coverage?
|
||||
- Do tests verify the right things?
|
||||
- Are tests maintainable?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] New code has tests
|
||||
- [ ] Tests cover main paths and edge cases
|
||||
@@ -120,11 +97,6 @@ Evaluate test coverage and quality.
|
||||
|
||||
Finally, check for security and performance concerns.
|
||||
|
||||
**Questions to Answer:**
|
||||
- Are there security vulnerabilities?
|
||||
- Are there performance issues?
|
||||
- Is data handled appropriately?
|
||||
|
||||
**Checklist:**
|
||||
- [ ] No SQL injection, XSS, etc.
|
||||
- [ ] Secrets not exposed
|
||||
@@ -167,40 +139,6 @@ Example:
|
||||
**Suggestion:** Add `if (!user) return null;` before accessing properties
|
||||
```
|
||||
|
||||
### Feedback Anti-Patterns
|
||||
|
||||
**Don't:**
|
||||
- "This is wrong" (not actionable)
|
||||
- "I would have done it differently" (without explanation)
|
||||
- "Why didn't you...?" (sounds accusatory)
|
||||
- Nitpicking on preferences (not conventions)
|
||||
|
||||
**Do:**
|
||||
- Be specific about the issue
|
||||
- Explain the impact
|
||||
- Offer a solution or alternative
|
||||
- Ask questions to understand intent
|
||||
|
||||
## Review Conversation
|
||||
|
||||
### Responding to Feedback
|
||||
|
||||
When receiving review comments:
|
||||
|
||||
1. **Acknowledge** - Confirm you've read and understood
|
||||
2. **Clarify** if needed - Ask questions if unclear
|
||||
3. **Address** - Make changes or explain why not
|
||||
4. **Resolve** - Mark as resolved when done
|
||||
|
||||
### Disagreeing Constructively
|
||||
|
||||
If you disagree with feedback:
|
||||
|
||||
```
|
||||
I see your point about [X]. In this case, I chose [Y] because [reason].
|
||||
Would you like to discuss further, or is this approach acceptable?
|
||||
```
|
||||
|
||||
## Review Checklist Summary
|
||||
|
||||
```markdown
|
||||
@@ -232,18 +170,6 @@ Would you like to discuss further, or is this approach acceptable?
|
||||
### Verdict: [ ] Approve [ ] Request Changes [ ] Comment
|
||||
```
|
||||
|
||||
## Time Management
|
||||
|
||||
For different PR sizes:
|
||||
|
||||
| Size | Expected Time | Approach |
|
||||
|------|---------------|----------|
|
||||
| Small (< 100 lines) | 10-15 minutes | Full structured review |
|
||||
| Medium (100-300 lines) | 20-30 minutes | Full structured review |
|
||||
| Large (300+ lines) | 45-60 minutes | Consider splitting PR |
|
||||
|
||||
If PR is too large, request it be split before review.
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
- **planning/verification-gates**: Review is a key gate
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Hypothesis Testing
|
||||
description: Scientific approach to debugging with hypothesis formation and testing
|
||||
name: hypothesis-testing
|
||||
description: Applies the scientific method to debugging by helping users form specific, testable hypotheses, design targeted experiments, and systematically confirm or reject theories to find root causes. Use when a user says their code isn't working, they're getting an error, something broke, they want to troubleshoot a bug, or they're trying to figure out what's causing an issue. Concrete actions include isolating failing components, forming and testing hypotheses, analyzing error messages, tracing execution paths, and interpreting test results to narrow down root causes.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- hypothesis
|
||||
@@ -51,26 +51,13 @@ Observations:
|
||||
|
||||
### 2. Hypothesize - Form Testable Theories
|
||||
|
||||
A good hypothesis is:
|
||||
- **Specific** - Points to a particular cause
|
||||
- **Testable** - Can be proven true or false
|
||||
- **Falsifiable** - Possible to prove wrong
|
||||
|
||||
**Bad hypotheses:**
|
||||
- "Something is wrong with the network"
|
||||
- "There might be a race condition"
|
||||
- "The code is buggy"
|
||||
|
||||
**Good hypotheses:**
|
||||
- "The inventory service connection pool is exhausted when processing orders with >10 items"
|
||||
- "The order processing timeout (5s) is insufficient for large orders"
|
||||
- "The new inventory service endpoint (v2) returns different response format"
|
||||
**Examples (bad → good):**
|
||||
- ~~"Something is wrong with the network"~~ → "The inventory service connection pool is exhausted when processing orders with >10 items"
|
||||
- ~~"There might be a race condition"~~ → "The order processing timeout (5s) is insufficient for large orders"
|
||||
|
||||
### 3. Predict - Define Expected Results
|
||||
|
||||
For each hypothesis, define:
|
||||
- If true, what should we observe?
|
||||
- If false, what should we observe?
|
||||
For each hypothesis, define what you expect to observe if it is true versus false:
|
||||
|
||||
```
|
||||
Hypothesis: Connection pool exhausted for large orders
|
||||
@@ -163,30 +150,6 @@ New hypothesis: Large orders make multiple inventory calls per item
|
||||
...
|
||||
```
|
||||
|
||||
## Common Debugging Hypotheses
|
||||
|
||||
### Performance Issues
|
||||
- "Query missing index on column X"
|
||||
- "N+1 query problem in relationship Y"
|
||||
- "Memory leak in component Z"
|
||||
- "Inefficient algorithm (O(n²)) in function F"
|
||||
|
||||
### Data Issues
|
||||
- "Invalid data in field X for certain records"
|
||||
- "Character encoding mismatch (UTF-8 vs Latin-1)"
|
||||
- "Stale cache serving outdated data"
|
||||
- "Race condition corrupting shared state"
|
||||
|
||||
### Configuration Issues
|
||||
- "Environment variable X not set in production"
|
||||
- "Timeout value too low for operation Y"
|
||||
- "Feature flag F enabled in wrong environment"
|
||||
|
||||
### Integration Issues
|
||||
- "API response format changed in version V"
|
||||
- "Certificate expired for service S"
|
||||
- "Rate limiting triggered by usage pattern P"
|
||||
|
||||
## Testing Techniques by Hypothesis Type
|
||||
|
||||
### Testing Timing Hypotheses
|
||||
@@ -221,23 +184,6 @@ if (stateBefore !== stateAfter) {
|
||||
}
|
||||
```
|
||||
|
||||
## Avoiding Hypothesis Bias
|
||||
|
||||
### Confirmation Bias
|
||||
- Don't only look for evidence supporting your favorite theory
|
||||
- Actively try to disprove your hypothesis
|
||||
- Give equal weight to contradicting evidence
|
||||
|
||||
### Anchoring Bias
|
||||
- Don't get stuck on first hypothesis
|
||||
- Be willing to abandon theories that don't fit evidence
|
||||
- Consider alternatives even when one seems likely
|
||||
|
||||
### Premature Closure
|
||||
- Don't stop at first plausible explanation
|
||||
- Verify the hypothesis completely before declaring victory
|
||||
- Consider if there might be multiple causes
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Root Cause Analysis
|
||||
description: Systematic approach to finding the true source of bugs, not just symptoms
|
||||
name: root-cause-analysis
|
||||
description: Performs systematic root cause analysis to identify the true source of bugs, errors, and unexpected behavior through structured investigation phases — not just treating symptoms. Use when a user reports a bug, crash, error, or broken behavior and needs to debug, troubleshoot, or investigate why something is not working; especially for complex or intermittent issues across multiple components. Applies the Five Whys method, hypothesis-driven testing, stack trace analysis, git blame/log evidence gathering, and causal chain documentation to isolate and confirm root causes before applying any fix.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- root cause
|
||||
@@ -29,22 +29,13 @@ You are performing systematic root cause analysis to find the true source of a b
|
||||
|
||||
**Never fix a symptom. Always find and fix the root cause.**
|
||||
|
||||
A root cause is the earliest point in the causal chain where intervention could prevent the defect.
|
||||
|
||||
## The Five Whys Method
|
||||
|
||||
Ask "Why?" repeatedly to drill down to the root cause:
|
||||
|
||||
1. **Why** did the API return an error?
|
||||
→ The database query failed
|
||||
2. **Why** did the database query fail?
|
||||
→ The connection timed out
|
||||
3. **Why** did the connection time out?
|
||||
→ The connection pool was exhausted
|
||||
4. **Why** was the connection pool exhausted?
|
||||
→ Connections weren't being released
|
||||
5. **Why** weren't connections being released?
|
||||
→ **ROOT CAUSE:** Missing `finally` block to close connections
|
||||
1. **Why** did the API return an error? → The database query failed
|
||||
2. **Why** did the database query fail? → The connection pool was exhausted
|
||||
3. **Why** was the pool exhausted? → **ROOT CAUSE:** Missing `finally` block to close connections
|
||||
|
||||
## Investigation Phases
|
||||
|
||||
@@ -66,15 +57,12 @@ Questions to answer:
|
||||
|
||||
Collect information before forming theories:
|
||||
|
||||
```
|
||||
Evidence Types:
|
||||
├── Error messages and stack traces
|
||||
├── Log files (application, system, database)
|
||||
├── Recent code changes (git log, blame)
|
||||
├── User reports and reproduction steps
|
||||
├── Monitoring data (metrics, APM)
|
||||
└── Related issues (search issue tracker)
|
||||
```
|
||||
- Error messages and stack traces
|
||||
- Log files (application, system, database)
|
||||
- Recent code changes (git log, blame)
|
||||
- User reports and reproduction steps
|
||||
- Monitoring data (metrics, APM)
|
||||
- Related issues (search issue tracker)
|
||||
|
||||
Do NOT:
|
||||
- Make changes while gathering evidence
|
||||
@@ -121,30 +109,10 @@ Before declaring root cause found:
|
||||
|
||||
## Common Root Cause Categories
|
||||
|
||||
### Code Defects
|
||||
- Logic errors
|
||||
- Boundary conditions
|
||||
- Race conditions
|
||||
- Resource leaks
|
||||
- Null/undefined handling
|
||||
|
||||
### Design Issues
|
||||
- Missing error handling
|
||||
- Inadequate validation
|
||||
- Poor state management
|
||||
- Coupling issues
|
||||
|
||||
### Environment
|
||||
- Configuration errors
|
||||
- Resource constraints
|
||||
- Version mismatches
|
||||
- Network issues
|
||||
|
||||
### Data Issues
|
||||
- Invalid input data
|
||||
- Data corruption
|
||||
- Schema mismatches
|
||||
- Encoding problems
|
||||
- **Code Defects:** logic errors, boundary conditions, race conditions, resource leaks, null/undefined handling
|
||||
- **Design Issues:** missing error handling, inadequate validation, poor state management, coupling
|
||||
- **Environment:** configuration errors, resource constraints, version mismatches, network issues
|
||||
- **Data Issues:** invalid input, data corruption, schema mismatches, encoding problems
|
||||
|
||||
## Evidence Collection Commands
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Trace and Isolate
|
||||
description: Techniques for tracing code execution and isolating problematic components
|
||||
name: trace-and-isolate
|
||||
description: Applies systematic tracing and isolation techniques to pinpoint exactly where a bug originates in code. Use when a bug is hard to locate, code is not working as expected, an error or crash appears with unclear cause, a regression was introduced between recent commits, or you need to narrow down which component, function, or line is faulty. Covers binary search debugging, git bisect for regressions, strategic logging with [TRACE] patterns, data and control flow tracing, component isolation, minimal reproduction cases, conditional breakpoints, and watch expressions across TypeScript, SQL, and bash.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- trace execution
|
||||
@@ -24,9 +24,16 @@ relatedSkills:
|
||||
|
||||
You are using systematic tracing and isolation techniques to narrow down where a bug originates. The goal is to find the exact location in code where behavior diverges from expectation.
|
||||
|
||||
## Core Principle
|
||||
## Quick Reference
|
||||
|
||||
**Divide and conquer. Systematically narrow the search space until you find the exact point of failure.**
|
||||
| Scenario | Technique |
|
||||
|---|---|
|
||||
| Large codebase / complex flow | Binary search debugging |
|
||||
| Bug appeared between commits | `git bisect` |
|
||||
| Unclear data transformation | Strategic `[TRACE]` logging |
|
||||
| Which component is faulty? | Component isolation + mocks |
|
||||
| Bug hard to reproduce | Minimal reproduction case |
|
||||
| Conditional or intermittent bug | Conditional breakpoints / watch expressions |
|
||||
|
||||
## Binary Search Debugging
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Skill Authoring
|
||||
description: Guidelines for writing effective AI agent skills
|
||||
name: skill-authoring
|
||||
description: Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- write a skill
|
||||
@@ -20,13 +20,13 @@ relatedSkills: []
|
||||
|
||||
# Skill Authoring Guide
|
||||
|
||||
You are authoring a skill for AI coding agents. A well-written skill provides clear, actionable guidance that agents can follow consistently.
|
||||
You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**A skill should be the description that triggers it, NOT a summary of the workflow.**
|
||||
**A skill's description triggers it; the body teaches it.**
|
||||
|
||||
The trigger/description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it.
|
||||
The description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it.
|
||||
|
||||
## Skill Anatomy
|
||||
|
||||
@@ -34,66 +34,49 @@ The trigger/description tells the agent WHEN to use the skill. The content tells
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Human-readable name]
|
||||
description: [What this skill does - for triggers]
|
||||
name: [lowercase-hyphenated-name]
|
||||
description: [Concrete actions + "Use when..." clause]
|
||||
version: [Semantic version]
|
||||
triggers:
|
||||
- [keyword 1]
|
||||
- [keyword 2]
|
||||
tags:
|
||||
- [tag 1]
|
||||
- [tag 2]
|
||||
difficulty: [beginner|intermediate|advanced]
|
||||
estimatedTime: [minutes]
|
||||
relatedSkills:
|
||||
- [pack/skill-name]
|
||||
---
|
||||
|
||||
# [Skill Title]
|
||||
|
||||
[Introduction paragraph explaining the skill's purpose]
|
||||
[Introduction paragraph explaining purpose]
|
||||
|
||||
## Core Principle
|
||||
|
||||
**[Single most important rule in bold]**
|
||||
|
||||
[Brief explanation of why this principle matters]
|
||||
|
||||
## [Main Content Sections]
|
||||
|
||||
[Detailed guidance organized into logical sections]
|
||||
## [Decision Points]
|
||||
|
||||
## [Decision Points / When to Use]
|
||||
|
||||
[Help the agent know when to apply this skill]
|
||||
|
||||
## [Verification / Checklist]
|
||||
|
||||
[How to verify the skill was applied correctly]
|
||||
## [Verification Checklist]
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
| Field | Required | Constraints |
|
||||
|-------|----------|-------------|
|
||||
| name | Yes | Human-readable skill name |
|
||||
| description | Yes | Brief description (triggers) |
|
||||
| version | Yes | Semantic version (1.0.0) |
|
||||
| triggers | Recommended | Keywords that activate skill |
|
||||
| name | Yes | Lowercase alphanumeric + hyphens, 1–64 chars |
|
||||
| description | Yes | Must include "Use when..." clause; 1–1024 chars |
|
||||
| version | Yes | Semantic version (e.g. `1.0.0`) |
|
||||
| triggers | Recommended | Natural-language phrases that activate the skill |
|
||||
| tags | Recommended | Categorization tags |
|
||||
| difficulty | Optional | beginner/intermediate/advanced |
|
||||
| estimatedTime | Optional | Minutes to apply |
|
||||
| relatedSkills | Optional | Related skill IDs |
|
||||
|
||||
## Writing Effective Triggers
|
||||
|
||||
Triggers should be phrases users naturally type:
|
||||
Triggers should be phrases users naturally type.
|
||||
|
||||
**Good triggers:**
|
||||
- "write tests first"
|
||||
- "tdd"
|
||||
- "test driven development"
|
||||
- "failing test before code"
|
||||
|
||||
**Bad triggers:**
|
||||
- "testing methodology" (too vague)
|
||||
@@ -102,10 +85,10 @@ Triggers should be phrases users naturally type:
|
||||
|
||||
### Trigger Guidelines
|
||||
|
||||
1. **Natural language** - How would a human ask for this?
|
||||
2. **Multiple variations** - Different ways to say the same thing
|
||||
3. **Specific enough** - Don't trigger on too many queries
|
||||
4. **Common terms** - Use terms people actually use
|
||||
1. **Natural language** — How would a human ask for this?
|
||||
2. **Multiple variations** — Different ways to say the same thing
|
||||
3. **Specific enough** — Don't trigger on too many queries
|
||||
4. **Common terms** — Use terms people actually use
|
||||
|
||||
## Writing Skill Content
|
||||
|
||||
@@ -113,47 +96,31 @@ Triggers should be phrases users naturally type:
|
||||
|
||||
Use **second person, present tense, active voice**:
|
||||
|
||||
- "You are implementing TDD"
|
||||
- "Write the test first"
|
||||
- "Verify the output"
|
||||
|
||||
Avoid:
|
||||
- "The developer should..." (passive)
|
||||
- "One might consider..." (vague)
|
||||
- "It is recommended that..." (wordy)
|
||||
- ✅ "Write the test first"
|
||||
- ✅ "You are implementing TDD"
|
||||
- ❌ "The developer should..." (passive)
|
||||
- ❌ "It is recommended that..." (wordy)
|
||||
|
||||
### Structure Guidelines
|
||||
|
||||
1. **Start with context** - What is the agent doing and why
|
||||
2. **State the core principle** - Most important rule upfront
|
||||
3. **Provide process** - Step-by-step guidance
|
||||
4. **Include examples** - Concrete illustrations
|
||||
5. **Add checklists** - Verification criteria
|
||||
6. **End with integration** - How this connects to other skills
|
||||
1. **Start with context** — What is the agent doing and why
|
||||
2. **State the core principle** — Most important rule upfront
|
||||
3. **Provide process** — Step-by-step guidance
|
||||
4. **Include examples** — Concrete illustrations
|
||||
5. **Add a checklist** — Verification criteria
|
||||
6. **End with integration** — How this connects to other skills
|
||||
|
||||
### Directive Language
|
||||
|
||||
Use clear, unambiguous directives:
|
||||
|
||||
**Strong directives:**
|
||||
- "You MUST..."
|
||||
- "ALWAYS..."
|
||||
- "NEVER..."
|
||||
- "Do NOT..."
|
||||
|
||||
**Softer guidance:**
|
||||
- "Prefer..."
|
||||
- "Consider..."
|
||||
- "When possible..."
|
||||
|
||||
Use strong directives for critical rules, softer guidance for recommendations.
|
||||
| Strength | Examples |
|
||||
|----------|----------|
|
||||
| Strong (critical rules) | "You MUST…", "ALWAYS…", "NEVER…", "Do NOT…" |
|
||||
| Soft (recommendations) | "Prefer…", "Consider…", "When possible…" |
|
||||
|
||||
## Content Patterns
|
||||
|
||||
### Decision Trees
|
||||
|
||||
When the agent needs to choose paths:
|
||||
|
||||
```markdown
|
||||
## Decision: [What to Decide]
|
||||
|
||||
@@ -169,8 +136,6 @@ If uncertain:
|
||||
|
||||
### Process Steps
|
||||
|
||||
For sequential workflows:
|
||||
|
||||
```markdown
|
||||
### Step 1: [Action]
|
||||
|
||||
@@ -182,90 +147,40 @@ For sequential workflows:
|
||||
...
|
||||
```
|
||||
|
||||
### Tables for Comparisons
|
||||
|
||||
```markdown
|
||||
| Situation | Action | Rationale |
|
||||
|-----------|--------|-----------|
|
||||
| [Case 1] | [Do X] | [Why] |
|
||||
| [Case 2] | [Do Y] | [Why] |
|
||||
```
|
||||
|
||||
### Code Examples
|
||||
|
||||
Show, don't just tell:
|
||||
|
||||
```typescript
|
||||
// BAD - Shows what NOT to do
|
||||
// BAD
|
||||
const result = doTheThing(badInput);
|
||||
|
||||
// GOOD - Shows correct approach
|
||||
// GOOD
|
||||
const validated = validate(input);
|
||||
const result = doTheThing(validated);
|
||||
```
|
||||
|
||||
### Checklists
|
||||
|
||||
For verification:
|
||||
|
||||
```markdown
|
||||
## Verification Checklist
|
||||
|
||||
Before marking complete:
|
||||
|
||||
- [ ] [Criterion 1]
|
||||
- [ ] [Criterion 2]
|
||||
- [ ] [Criterion 3]
|
||||
```
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### The Encyclopedia
|
||||
|
||||
**Problem:** Too much information, agent gets lost
|
||||
**Fix:** Focus on actionable guidance, link to details
|
||||
|
||||
### The Vague Guide
|
||||
|
||||
**Problem:** "Consider best practices" (What practices?)
|
||||
**Fix:** Be specific: "Use Arrange-Act-Assert pattern"
|
||||
|
||||
### The Constraint-Free Skill
|
||||
|
||||
**Problem:** No clear rules, agent improvises
|
||||
**Fix:** Include explicit constraints and rules
|
||||
|
||||
### The Monologue
|
||||
|
||||
**Problem:** Wall of text with no structure
|
||||
**Fix:** Use headers, lists, tables, code blocks
|
||||
|
||||
### The Outdated Skill
|
||||
|
||||
**Problem:** References deprecated patterns/tools
|
||||
**Fix:** Version skills, include validity dates
|
||||
| Anti-pattern | Problem | Fix |
|
||||
|--------------|---------|-----|
|
||||
| The Encyclopedia | Too much info, agent gets lost | Focus on actionable guidance only |
|
||||
| The Vague Guide | "Consider best practices" | Be specific: "Use Arrange-Act-Assert" |
|
||||
| The Constraint-Free Skill | No clear rules, agent improvises | Include explicit constraints |
|
||||
| The Monologue | Wall of text | Use headers, lists, tables, code blocks |
|
||||
| The Outdated Skill | References deprecated patterns | Version skills and review periodically |
|
||||
|
||||
## Skill Testing
|
||||
|
||||
Before publishing, verify:
|
||||
|
||||
1. **Trigger test** - Does it activate on expected phrases?
|
||||
2. **Completeness test** - Can agent follow without external info?
|
||||
3. **Clarity test** - Is every instruction unambiguous?
|
||||
4. **Contradiction test** - No conflicting guidance?
|
||||
5. **Edge case test** - Handles unusual situations?
|
||||
|
||||
### Manual Verification
|
||||
|
||||
```
|
||||
Test Query: "[trigger phrase]"
|
||||
Expected: Skill activates and provides relevant guidance
|
||||
Actual: [Record what happened]
|
||||
```
|
||||
1. **Trigger test** — Does it activate on expected phrases?
|
||||
2. **Completeness test** — Can the agent follow it without external info?
|
||||
3. **Clarity test** — Is every instruction unambiguous?
|
||||
4. **Contradiction test** — No conflicting guidance?
|
||||
5. **Edge case test** — Handles unusual situations?
|
||||
|
||||
## Pack Organization
|
||||
|
||||
Skills should be organized into methodology packs:
|
||||
Group related skills under a named pack directory. See `PACKS.md` for full pack manifest format and filesystem conventions.
|
||||
|
||||
```
|
||||
packs/
|
||||
@@ -275,59 +190,38 @@ packs/
|
||||
│ │ └── SKILL.md
|
||||
│ └── test-patterns/
|
||||
│ └── SKILL.md
|
||||
├── debugging/
|
||||
│ ├── pack.json
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
### Pack Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "testing",
|
||||
"version": "1.0.0",
|
||||
"description": "Testing methodology skills",
|
||||
"skills": ["red-green-refactor", "test-patterns"],
|
||||
"tags": ["testing", "tdd", "quality"],
|
||||
"compatibility": ["all"]
|
||||
}
|
||||
```
|
||||
|
||||
## Skill Maintenance
|
||||
|
||||
### Version Updates
|
||||
See `MAINTENANCE.md` for detailed versioning policy. Quick reference:
|
||||
|
||||
When to increment version:
|
||||
**Version increments:**
|
||||
- **Patch (1.0.x):** Typos, clarifications, minor fixes
|
||||
- **Minor (1.x.0):** New sections, examples, capabilities
|
||||
- **Major (x.0.0):** Breaking changes, fundamental rewrites
|
||||
|
||||
### Deprecation
|
||||
**Deprecation frontmatter:**
|
||||
|
||||
If skill becomes obsolete:
|
||||
|
||||
```markdown
|
||||
---
|
||||
```yaml
|
||||
deprecated: true
|
||||
deprecatedReason: "Superseded by skill-v2"
|
||||
deprecatedSince: "2024-01-15"
|
||||
---
|
||||
|
||||
> **DEPRECATED:** This skill is deprecated. Use [skill-v2] instead.
|
||||
|
||||
[Original content for reference]
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
Add a visible notice at the top of the body: `> **DEPRECATED:** Use [skill-v2] instead.`
|
||||
|
||||
Before publishing:
|
||||
## Publication Checklist
|
||||
|
||||
- [ ] Frontmatter is complete and valid
|
||||
- [ ] Triggers are natural and specific
|
||||
Before publishing, confirm:
|
||||
|
||||
- [ ] Frontmatter is complete and valid (name, description, version)
|
||||
- [ ] Description includes concrete actions and a "Use when…" clause
|
||||
- [ ] Triggers are natural-language phrases, specific but not over-fitted
|
||||
- [ ] Core principle is clear and prominent
|
||||
- [ ] Content is structured with headers
|
||||
- [ ] Examples are included
|
||||
- [ ] Verification checklist exists
|
||||
- [ ] Related skills are linked
|
||||
- [ ] Content uses headers, lists, or tables — no walls of text
|
||||
- [ ] Code examples demonstrate correct vs. incorrect usage
|
||||
- [ ] Verification criteria are included
|
||||
- [ ] Related skills are linked where applicable
|
||||
- [ ] No spelling/grammar errors
|
||||
- [ ] Tested with target agents
|
||||
- [ ] Tested with target agents against all trigger phrases
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Design First
|
||||
description: Think before coding - design the solution before implementing
|
||||
name: design-first
|
||||
description: Guides the creation of technical design documents before writing code, producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses. Use when the user asks to plan a feature, architect a system, design an API, explore implementation approaches, or requests a technical design or spec before coding — especially for complex features involving multiple components, ambiguous requirements, or significant architectural changes.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- design first
|
||||
@@ -22,13 +22,11 @@ relatedSkills:
|
||||
|
||||
# Design First Methodology
|
||||
|
||||
You are following a design-first approach. Before writing any code, design the solution. This prevents costly rewrites and ensures the implementation meets requirements.
|
||||
You are following a design-first approach. Before writing any code, design the solution.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Think first, code second. A good design makes implementation straightforward.**
|
||||
|
||||
The cost of changing a design is 10x lower than changing code. Invest time in design to save time overall.
|
||||
**Think first, code second.**
|
||||
|
||||
## When to Use Design First
|
||||
|
||||
@@ -158,50 +156,19 @@ Before implementing, validate:
|
||||
|
||||
## Design Document Template
|
||||
|
||||
```markdown
|
||||
# Design: [Feature Name]
|
||||
Use `DESIGN_TEMPLATE.md` as the standard artifact for each feature. It covers:
|
||||
|
||||
## Overview
|
||||
[One paragraph summary of what we're building and why]
|
||||
- **Overview** — one-paragraph summary of what is being built and why
|
||||
- **Requirements** — functional and non-functional (performance, security)
|
||||
- **Architecture** — component diagram and explanation
|
||||
- **Data Model** — entity definitions and relationships
|
||||
- **API Design** — interface definitions
|
||||
- **Key Decisions** — decision table with options considered, choice made, and rationale
|
||||
- **Implementation Plan** — ordered steps
|
||||
- **Testing Strategy** — unit and integration test scope
|
||||
- **Open Questions** — unresolved items
|
||||
|
||||
## Requirements
|
||||
### Functional
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
|
||||
### Non-Functional
|
||||
- [Performance requirement]
|
||||
- [Security requirement]
|
||||
|
||||
## Design
|
||||
|
||||
### Architecture
|
||||
[Diagram and explanation of components]
|
||||
|
||||
### Data Model
|
||||
[Entity definitions and relationships]
|
||||
|
||||
### API Design
|
||||
[Interface definitions]
|
||||
|
||||
### Key Decisions
|
||||
| Decision | Options Considered | Choice | Rationale |
|
||||
|----------|-------------------|--------|-----------|
|
||||
| Database | PostgreSQL, MongoDB | PostgreSQL | Need ACID transactions |
|
||||
|
||||
## Implementation Plan
|
||||
1. [First step]
|
||||
2. [Second step]
|
||||
...
|
||||
|
||||
## Testing Strategy
|
||||
- Unit tests for [X]
|
||||
- Integration tests for [Y]
|
||||
|
||||
## Open Questions
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
```
|
||||
Create this file at the start of each design session and keep it updated as the design evolves.
|
||||
|
||||
## Design Levels
|
||||
|
||||
@@ -225,20 +192,11 @@ Before implementing, validate:
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### Big Design Up Front (BDUF)
|
||||
- Don't over-design every detail
|
||||
- Design enough to start, refine as you learn
|
||||
- Balance planning with doing
|
||||
|
||||
### Analysis Paralysis
|
||||
- Set a time limit for design phase
|
||||
- Make decisions with 70% confidence
|
||||
- Plan to iterate
|
||||
|
||||
### Design in Isolation
|
||||
- Consider existing patterns in codebase
|
||||
- Align with team conventions
|
||||
- Don't reinvent existing solutions
|
||||
| Anti-Pattern | Mitigation |
|
||||
|---|---|
|
||||
| Big Design Up Front (BDUF) | Design enough to start; refine as you learn |
|
||||
| Analysis Paralysis | Time-box the design phase; decide at 70% confidence |
|
||||
| Design in Isolation | Align with existing codebase patterns and team conventions |
|
||||
|
||||
## Integration with Implementation
|
||||
|
||||
@@ -249,7 +207,7 @@ After design is approved:
|
||||
3. **Implement incrementally** - verify design assumptions as you code
|
||||
4. **Update design** if you discover issues during implementation
|
||||
|
||||
The design document is living - update it as you learn.
|
||||
The design document is living — update it as you learn.
|
||||
|
||||
## Signals You Need More Design
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Task Decomposition
|
||||
description: Break down complex tasks into small, manageable, atomic units
|
||||
name: task-decomposition
|
||||
description: Breaks down complex software, writing, or research tasks into small, atomic, independently completable units with dependency graphs and milestone breakdowns. Use when the user asks to plan a project, decompose a feature, create subtasks, split up work, or needs help organizing a large piece of work into a step-by-step plan. Triggered by phrases like "break down", "decompose", "where do I start", "too big", "split into tasks", "work breakdown", or "task list".
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- break down
|
||||
@@ -29,81 +29,32 @@ You are breaking down a complex task into smaller, atomic units. Each unit shoul
|
||||
|
||||
**If a task feels too big, it is too big. Break it down until each piece is obvious.**
|
||||
|
||||
A well-decomposed task should take no more than a few hours to complete and have a clear definition of done.
|
||||
|
||||
## What Makes a Good Atomic Task
|
||||
|
||||
A properly decomposed task is:
|
||||
|
||||
- **Small** - Completable in one focused session
|
||||
- **Independent** - Can be done without blocking on other tasks
|
||||
- **Testable** - Has clear success criteria
|
||||
- **Valuable** - Delivers some increment of value
|
||||
- **Estimatable** - Scope is clear enough to estimate
|
||||
|
||||
**Task Size Targets:**
|
||||
- Ideal: 1-2 hours of focused work
|
||||
- Maximum: Half a day
|
||||
- If larger: Break it down further
|
||||
A well-decomposed task should take no more than a few hours to complete and have a clear definition of done. Aim for tasks that are small, independent, testable, and clearly scoped.
|
||||
|
||||
## Decomposition Techniques
|
||||
|
||||
### 1. Vertical Slicing
|
||||
|
||||
Break by user-visible functionality:
|
||||
Break by user-visible functionality (each slice is deployable and testable independently):
|
||||
|
||||
```
|
||||
Feature: User Registration
|
||||
|
||||
Slice 1: Email/password signup
|
||||
- Form renders with email and password fields
|
||||
- Validation shows errors for invalid input
|
||||
- Success creates account and shows confirmation
|
||||
|
||||
Slice 2: Email verification
|
||||
- Sends verification email on signup
|
||||
- Clicking link verifies email
|
||||
- Shows different UI for unverified accounts
|
||||
|
||||
Slice 3: Social login (OAuth)
|
||||
- "Sign in with Google" button
|
||||
- OAuth flow completes
|
||||
- Account linked to Google ID
|
||||
Slice 1: Email/password signup — form, validation, account creation
|
||||
Slice 2: Email verification — send email, verify link, UI state
|
||||
Slice 3: Social login (OAuth) — Google button, OAuth flow, account link
|
||||
```
|
||||
|
||||
Each slice is deployable and testable independently.
|
||||
|
||||
### 2. Horizontal Layering
|
||||
|
||||
Break by system layer:
|
||||
|
||||
```
|
||||
Feature: Order Processing
|
||||
|
||||
Layer 1: Data Model
|
||||
- Create Order entity
|
||||
- Create OrderItem entity
|
||||
- Add database migrations
|
||||
|
||||
Layer 2: Repository/Data Access
|
||||
- Create OrderRepository
|
||||
- Implement CRUD operations
|
||||
- Add query methods
|
||||
|
||||
Layer 3: Business Logic
|
||||
- Create OrderService
|
||||
- Implement order creation flow
|
||||
- Add validation rules
|
||||
|
||||
Layer 4: API Endpoints
|
||||
- Create POST /orders endpoint
|
||||
- Create GET /orders/:id endpoint
|
||||
- Add error handling
|
||||
|
||||
Layer 5: Frontend Integration
|
||||
- Create order form component
|
||||
- Add API client methods
|
||||
- Handle loading and error states
|
||||
Layer 1: Data Model — entities, migrations
|
||||
Layer 2: Data Access — repository, CRUD, queries
|
||||
Layer 3: Business Logic — service, validation rules
|
||||
Layer 4: API Endpoints — routes, error handling
|
||||
Layer 5: Frontend — form, API client, loading/error states
|
||||
```
|
||||
|
||||
### 3. Workflow Decomposition
|
||||
@@ -111,27 +62,11 @@ Layer 5: Frontend Integration
|
||||
Break by process steps:
|
||||
|
||||
```
|
||||
Task: Implement checkout flow
|
||||
|
||||
Step 1: Cart validation
|
||||
- Verify items are in stock
|
||||
- Validate quantities
|
||||
- Calculate totals
|
||||
|
||||
Step 2: Payment processing
|
||||
- Collect payment details
|
||||
- Validate payment method
|
||||
- Process transaction
|
||||
|
||||
Step 3: Order creation
|
||||
- Create order record
|
||||
- Associate with payment
|
||||
- Update inventory
|
||||
|
||||
Step 4: Confirmation
|
||||
- Send confirmation email
|
||||
- Display success page
|
||||
- Generate invoice
|
||||
Task: Checkout flow
|
||||
Step 1: Cart validation — stock check, quantities, totals
|
||||
Step 2: Payment — collect details, validate, process
|
||||
Step 3: Order creation — record, payment link, inventory update
|
||||
Step 4: Confirmation — email, success page, invoice
|
||||
```
|
||||
|
||||
### 4. Component Decomposition
|
||||
@@ -139,27 +74,15 @@ Step 4: Confirmation
|
||||
Break by UI or system component:
|
||||
|
||||
```
|
||||
Task: Build dashboard page
|
||||
|
||||
Component 1: Header section
|
||||
- Logo and navigation
|
||||
- User menu dropdown
|
||||
|
||||
Component 2: Stats cards row
|
||||
- Revenue card
|
||||
- Orders card
|
||||
- Customers card
|
||||
|
||||
Component 3: Chart section
|
||||
- Sales trend chart
|
||||
- Data fetching and transformation
|
||||
|
||||
Component 4: Recent orders table
|
||||
- Table with sorting
|
||||
- Pagination
|
||||
- Row actions
|
||||
Task: Dashboard page
|
||||
Component 1: Header — logo, nav, user menu
|
||||
Component 2: Stats cards — revenue, orders, customers
|
||||
Component 3: Chart — sales trend, data fetch/transform
|
||||
Component 4: Orders table — sort, pagination, row actions
|
||||
```
|
||||
|
||||
> For more detailed worked examples of each technique, see `EXAMPLES.md`.
|
||||
|
||||
## Task Template
|
||||
|
||||
For each decomposed task, define:
|
||||
@@ -235,97 +158,11 @@ Phase 3 (Depends on Phase 2):
|
||||
|
||||
For each task, verify:
|
||||
|
||||
- [ ] **Atomic?** - Can be done without interruption
|
||||
- [ ] **Clear?** - Scope is unambiguous
|
||||
- [ ] **Testable?** - Know when it's done
|
||||
- [ ] **Independent?** - Minimal dependencies
|
||||
- [ ] **Small?** - Less than half a day
|
||||
|
||||
## Signs of Poor Decomposition
|
||||
|
||||
- "This task keeps growing"
|
||||
- "I'm not sure where to start"
|
||||
- "It depends on too many things"
|
||||
- "I can't test it yet"
|
||||
- "This is taking longer than expected"
|
||||
|
||||
When you see these signs, stop and re-decompose.
|
||||
|
||||
## Example: Full Decomposition
|
||||
|
||||
```markdown
|
||||
# Feature: Password Reset
|
||||
|
||||
## Epic Overview
|
||||
Users can reset their forgotten password via email link.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Password Reset Request API
|
||||
|
||||
**Description:** Create endpoint to request password reset.
|
||||
|
||||
**Files:**
|
||||
- [ ] src/api/auth/reset-request.ts
|
||||
- [ ] src/services/email/templates/reset.html
|
||||
|
||||
**Steps:**
|
||||
1. Create POST /auth/reset-password endpoint
|
||||
2. Validate email exists in database
|
||||
3. Generate secure reset token
|
||||
4. Store token with expiry (1 hour)
|
||||
5. Send email with reset link
|
||||
|
||||
**Done When:**
|
||||
- [ ] Endpoint returns 200 for valid email
|
||||
- [ ] Endpoint returns 200 for invalid email (no leak)
|
||||
- [ ] Email sent with valid token
|
||||
- [ ] Token stored in database
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Password Reset Form UI
|
||||
|
||||
**Description:** Create form for entering new password.
|
||||
|
||||
**Files:**
|
||||
- [ ] src/pages/reset-password.tsx
|
||||
- [ ] src/components/PasswordResetForm.tsx
|
||||
|
||||
**Steps:**
|
||||
1. Create page component at /reset-password?token=X
|
||||
2. Build form with password and confirm fields
|
||||
3. Add password strength validation
|
||||
4. Show loading state during submission
|
||||
|
||||
**Done When:**
|
||||
- [ ] Form renders with token in URL
|
||||
- [ ] Validation shows for weak passwords
|
||||
- [ ] Form submits to API
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Password Reset Complete API
|
||||
|
||||
**Description:** Create endpoint to set new password.
|
||||
|
||||
**Files:**
|
||||
- [ ] src/api/auth/reset-complete.ts
|
||||
|
||||
**Steps:**
|
||||
1. Create POST /auth/reset-password/complete endpoint
|
||||
2. Validate token is valid and not expired
|
||||
3. Hash new password
|
||||
4. Update user record
|
||||
5. Invalidate token
|
||||
6. Return success
|
||||
|
||||
**Done When:**
|
||||
- [ ] Valid token + new password updates user
|
||||
- [ ] Expired token returns error
|
||||
- [ ] Invalid token returns error
|
||||
- [ ] Token cannot be reused
|
||||
```
|
||||
- [ ] **Atomic?** — Can be done without interruption
|
||||
- [ ] **Clear?** — Scope is unambiguous
|
||||
- [ ] **Testable?** — Know when it's done
|
||||
- [ ] **Independent?** — Minimal dependencies
|
||||
- [ ] **Small?** — Less than half a day
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Verification Gates
|
||||
description: Define checkpoints to validate work before proceeding to next phase
|
||||
name: verification-gates
|
||||
description: Creates explicit validation checkpoints (verification gates) between project phases to catch errors early and ensure quality before proceeding. Use when the user asks about quality gates, milestone checks, phase transitions, approval steps, go/no-go decision points, or preventing cascading errors across a multi-step workflow. Produces acceptance criteria checklists, automated CI gate configurations, manual sign-off requirements, and conditional review rules for scenarios such as security changes, API changes, or database migrations.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- verify before
|
||||
@@ -31,24 +31,6 @@ You are implementing verification gates - explicit checkpoints where work is val
|
||||
|
||||
A verification gate is a deliberate pause to confirm that prerequisites are met before continuing.
|
||||
|
||||
## Why Verification Gates Matter
|
||||
|
||||
Without gates:
|
||||
```
|
||||
Phase 1 → Phase 2 → Phase 3 → Phase 4
|
||||
↑
|
||||
└── Error discovered at Phase 4
|
||||
Must redo Phases 2, 3, 4
|
||||
```
|
||||
|
||||
With gates:
|
||||
```
|
||||
Phase 1 → [Gate] → Phase 2 → [Gate] → Phase 3 → [Gate] → Phase 4
|
||||
↑
|
||||
└── Error caught immediately
|
||||
Only redo Phase 1
|
||||
```
|
||||
|
||||
## Standard Verification Gates
|
||||
|
||||
### Gate 1: Requirements Verification
|
||||
@@ -244,34 +226,9 @@ Task Complete
|
||||
**Approver:** [Who can approve passage]
|
||||
```
|
||||
|
||||
## Common Gate Failures
|
||||
|
||||
### "Just this once" Syndrome
|
||||
- **Problem:** Skipping gates for urgent work
|
||||
- **Fix:** Urgent work gets simpler gates, not no gates
|
||||
|
||||
### Gate Inflation
|
||||
- **Problem:** Too many gates slow everything down
|
||||
- **Fix:** Only gates that catch real issues
|
||||
|
||||
### Rubber Stamp Gates
|
||||
- **Problem:** Gates passed without real verification
|
||||
- **Fix:** Specific checklists, evidence requirements
|
||||
|
||||
## Gate Metrics
|
||||
|
||||
Track gate effectiveness:
|
||||
|
||||
```
|
||||
Gate Effectiveness = Issues caught at gate / Total issues
|
||||
Gate Overhead = Time spent at gates / Total development time
|
||||
Gate Value = (Cost of issue caught early) / (Gate overhead cost)
|
||||
```
|
||||
|
||||
Good gates have:
|
||||
- High effectiveness (catch most issues)
|
||||
- Low overhead (quick to pass)
|
||||
- High value (prevent expensive fixes)
|
||||
Good gates have high effectiveness (catch most issues), low overhead (quick to pass), and high value (prevent expensive downstream fixes). Track which gate caught an issue and how much time was spent at each gate to tune your process over time.
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Testing Anti-Patterns
|
||||
description: Common testing mistakes to avoid for reliable, maintainable tests
|
||||
name: testing-anti-patterns
|
||||
description: Reviews test code to identify and fix common testing anti-patterns including flaky tests, over-mocking, brittle assertions, test interdependency, and hidden test logic. Flags bad patterns, explains the specific defect, and provides corrected implementations. Use when reviewing test code, debugging intermittent or unreliable test failures, or when the user mentions flaky tests, test smells, brittle tests, test isolation issues, mock overuse, slow tests, or test maintenance problems.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- test anti-patterns
|
||||
@@ -22,7 +22,16 @@ relatedSkills:
|
||||
|
||||
# Testing Anti-Patterns
|
||||
|
||||
You are identifying and avoiding common testing anti-patterns. These patterns lead to unreliable tests, false confidence, and maintenance burden.
|
||||
You are identifying and avoiding common testing anti-patterns.
|
||||
|
||||
## Review Workflow
|
||||
|
||||
Follow these steps when reviewing test code:
|
||||
|
||||
1. **Run tests in isolation** — Verify each test passes independently (no shared state, no ordering dependency).
|
||||
2. **Check for patterns below** — Scan for each anti-pattern in the checklist; flag every match with the specific defect.
|
||||
3. **Apply refactoring strategy** — Use the refactoring strategies section to select and apply the appropriate fix.
|
||||
4. **Verify the test still fails when code breaks** — After fixing, confirm the corrected test catches real regressions (remove or stub the implementation to confirm a failure occurs).
|
||||
|
||||
## Critical Anti-Patterns
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Red-Green-Refactor
|
||||
description: Test-driven development cycle for writing reliable, well-designed code
|
||||
name: red-green-refactor
|
||||
description: "Guides the red-green-refactor TDD workflow: write a failing test first, implement the minimum code to make it pass, then refactor while keeping tests green. Use when a user asks to practice TDD, write tests first, follow red-green-refactor, do test-driven development, write failing tests before code, or phrases like 'make the test pass', 'test coverage', or 'unit tests before implementation'."
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- tdd
|
||||
@@ -22,97 +22,131 @@ relatedSkills:
|
||||
|
||||
# Red-Green-Refactor Methodology
|
||||
|
||||
You are following the RED-GREEN-REFACTOR cycle for test-driven development. This methodology ensures code is thoroughly tested and well-designed through iterative cycles.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Write a failing test BEFORE writing any production code.**
|
||||
|
||||
This is not optional. Every new feature, bug fix, or behavior change starts with a test that demonstrates the requirement.
|
||||
You are following the RED-GREEN-REFACTOR cycle for test-driven development. Every new feature, bug fix, or behavior change starts with a failing test.
|
||||
|
||||
## The Cycle
|
||||
|
||||
### 1. RED Phase - Write a Failing Test
|
||||
### 1. RED Phase — Write a Failing Test
|
||||
|
||||
Before writing any implementation:
|
||||
1. **Understand the requirement** — what specific behavior must exist?
|
||||
2. **Write one test** asserting that behavior
|
||||
3. **Run the test** — it MUST fail (red)
|
||||
4. **Verify the failure reason** — not a syntax error, but a missing implementation
|
||||
|
||||
1. **Understand the requirement** - What specific behavior needs to exist?
|
||||
2. **Write a test** that asserts this behavior
|
||||
3. **Run the test** - It MUST fail (red)
|
||||
4. **Verify the failure** - Ensure it fails for the right reason, not due to syntax errors
|
||||
The test should be focused on ONE behavior, named descriptively, and use clear assertions.
|
||||
|
||||
The test should be:
|
||||
- Focused on ONE specific behavior
|
||||
- Named to describe what is being tested
|
||||
- Using clear assertions with meaningful error messages
|
||||
**Executable example (Jest):**
|
||||
```js
|
||||
// calculateTotal.test.js
|
||||
const { calculateTotal } = require('./calculateTotal');
|
||||
|
||||
```
|
||||
Example test structure:
|
||||
describe('calculateTotal', () => {
|
||||
it('should apply discount when total exceeds threshold', () => {
|
||||
// Arrange - set up test data
|
||||
// Act - call the function
|
||||
// Assert - verify the result
|
||||
it('should apply 10% discount when total exceeds 100', () => {
|
||||
const items = [{ price: 60 }, { price: 60 }]; // total = 120
|
||||
expect(calculateTotal(items)).toBe(108); // 120 * 0.90
|
||||
});
|
||||
});
|
||||
```
|
||||
Running this now produces: `Cannot find module './calculateTotal'` — correct RED state.
|
||||
|
||||
### 2. GREEN Phase - Make the Test Pass
|
||||
---
|
||||
|
||||
Write the MINIMUM code necessary to make the test pass:
|
||||
### 2. GREEN Phase — Make the Test Pass
|
||||
|
||||
1. **Focus on passing**, not perfection
|
||||
2. **Take the simplest path** - Even hardcoding is acceptable initially
|
||||
3. **Do not add features** the test doesn't require
|
||||
4. **Run the test** - It MUST pass (green)
|
||||
Write the **minimum code** needed to pass the test. Don't add anything extra.
|
||||
|
||||
Guidelines:
|
||||
- If tempted to write more code than needed, STOP
|
||||
- The goal is a passing test, not elegant code
|
||||
- Ugly code is acceptable at this stage
|
||||
```js
|
||||
// calculateTotal.js
|
||||
function calculateTotal(items) {
|
||||
const total = items.reduce((sum, item) => sum + item.price, 0);
|
||||
return total > 100 ? total * 0.9 : total;
|
||||
}
|
||||
module.exports = { calculateTotal };
|
||||
```
|
||||
Run the test — it passes. GREEN achieved. Stop here; resist adding more logic.
|
||||
|
||||
### 3. REFACTOR Phase - Improve the Code
|
||||
---
|
||||
|
||||
With a passing test as your safety net:
|
||||
### 3. REFACTOR Phase — Improve the Code
|
||||
|
||||
1. **Identify code smells** - Duplication, long methods, unclear names
|
||||
2. **Refactor incrementally** - Small changes, run tests after each
|
||||
3. **Maintain green** - Tests must pass after every change
|
||||
4. **Stop when clean** - Don't over-engineer
|
||||
With a passing test as your safety net, clean up the implementation. Run tests after every change.
|
||||
|
||||
Common refactorings:
|
||||
- Extract method/function
|
||||
- Rename for clarity
|
||||
- Remove duplication
|
||||
- Simplify conditionals
|
||||
```js
|
||||
// calculateTotal.js — refactored for clarity
|
||||
const DISCOUNT_THRESHOLD = 100;
|
||||
const DISCOUNT_RATE = 0.9;
|
||||
|
||||
## Workflow Commands
|
||||
function calculateTotal(items) {
|
||||
const subtotal = items.reduce((sum, { price }) => sum + price, 0);
|
||||
return subtotal > DISCOUNT_THRESHOLD ? subtotal * DISCOUNT_RATE : subtotal;
|
||||
}
|
||||
module.exports = { calculateTotal };
|
||||
```
|
||||
Test still passes — GREEN maintained. Constants now communicate intent.
|
||||
|
||||
When implementing a feature or fix:
|
||||
---
|
||||
|
||||
1. **Start with a test file** - Create or update the test file first
|
||||
2. **Write ONE failing test** - Focus on the smallest testable unit
|
||||
3. **Implement minimally** - Just enough to pass
|
||||
4. **Refactor if needed** - Clean up while tests are green
|
||||
5. **Repeat** - Next test for next behavior
|
||||
## End-to-End Example: Adding a New Behavior
|
||||
|
||||
**Next requirement:** apply a 15% discount when total exceeds 200.
|
||||
|
||||
**RED** — write the failing test first:
|
||||
```js
|
||||
it('should apply 15% discount when total exceeds 200', () => {
|
||||
const items = [{ price: 110 }, { price: 110 }]; // total = 220
|
||||
expect(calculateTotal(items)).toBe(187); // 220 * 0.85
|
||||
});
|
||||
```
|
||||
|
||||
**GREEN** — extend the implementation minimally:
|
||||
```js
|
||||
function calculateTotal(items) {
|
||||
const subtotal = items.reduce((sum, { price }) => sum + price, 0);
|
||||
if (subtotal > 200) return subtotal * 0.85;
|
||||
if (subtotal > 100) return subtotal * 0.9;
|
||||
return subtotal;
|
||||
}
|
||||
```
|
||||
|
||||
**REFACTOR** — remove duplication with a tiered structure:
|
||||
```js
|
||||
const DISCOUNT_TIERS = [
|
||||
{ threshold: 200, rate: 0.85 },
|
||||
{ threshold: 100, rate: 0.9 },
|
||||
];
|
||||
|
||||
function calculateTotal(items) {
|
||||
const subtotal = items.reduce((sum, { price }) => sum + price, 0);
|
||||
const tier = DISCOUNT_TIERS.find(({ threshold }) => subtotal > threshold);
|
||||
return tier ? subtotal * tier.rate : subtotal;
|
||||
}
|
||||
```
|
||||
Both tests pass — ready for the next cycle.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
1. **Create or open the test file first**
|
||||
2. **Write ONE failing test** for the smallest testable unit
|
||||
3. **Implement minimally** — just enough to pass
|
||||
4. **Refactor if needed** — while tests stay green
|
||||
5. **Repeat** for the next behavior
|
||||
|
||||
## Decision Points
|
||||
|
||||
### When to Write a New Test
|
||||
### Write a new test when:
|
||||
- Adding a new feature or behavior
|
||||
- Fixing a bug (test the bug first)
|
||||
- Changing existing behavior
|
||||
- Edge cases discovered during implementation
|
||||
- Fixing a bug (test the bug first, then fix it)
|
||||
- Handling an edge case discovered during implementation
|
||||
|
||||
### When NOT to Write a Test
|
||||
- Pure refactoring (existing tests cover it)
|
||||
### Don't write a test when:
|
||||
- Pure refactoring (existing tests already cover the behavior)
|
||||
- Non-functional changes (formatting, comments)
|
||||
- Third-party library behavior
|
||||
- Third-party library internals
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before considering work complete:
|
||||
|
||||
- [ ] All new code has corresponding tests
|
||||
- [ ] Tests fail when the feature is removed
|
||||
- [ ] Tests pass consistently (not flaky)
|
||||
@@ -121,15 +155,14 @@ Before considering work complete:
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
1. **Writing tests after code** - Defeats the purpose of TDD
|
||||
2. **Writing too many tests at once** - One test at a time
|
||||
3. **Making tests pass with hacks** - The test should drive good design
|
||||
4. **Skipping the refactor phase** - Technical debt accumulates
|
||||
5. **Testing implementation details** - Test behavior, not internals
|
||||
1. **Writing tests after code** — defeats the design benefit of TDD
|
||||
2. **Writing multiple tests at once** — one test drives one change
|
||||
3. **Passing tests with hacks** — the test should drive good design
|
||||
4. **Skipping the refactor phase** — technical debt accumulates
|
||||
5. **Testing implementation details** — test behavior, not internals
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
This skill works well with:
|
||||
- **test-patterns**: Provides patterns for structuring tests
|
||||
- **anti-patterns**: Helps avoid common testing mistakes
|
||||
- **test-patterns**: Patterns for structuring tests
|
||||
- **anti-patterns**: Common testing mistakes to avoid
|
||||
- **debugging/root-cause-analysis**: When tests reveal unexpected failures
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: Test Patterns
|
||||
description: Effective patterns for writing maintainable, reliable tests
|
||||
name: test-patterns
|
||||
description: Applies proven testing patterns — Arrange-Act-Assert (AAA), Given-When-Then, Test Data Builders, Object Mother, parameterized tests, fixtures, spies, and test doubles — to help write maintainable, reliable, and readable test suites. Use when the user asks about writing unit tests, integration tests, or end-to-end tests; structuring test cases or test suites; applying TDD or BDD practices; working with mocks, stubs, spies, or fakes; improving test coverage or reducing flakiness; or needs guidance on test organization, naming conventions, or assertions in frameworks like Jest, Vitest, pytest, or similar.
|
||||
version: 1.0.0
|
||||
triggers:
|
||||
- test patterns
|
||||
@@ -24,6 +24,39 @@ relatedSkills:
|
||||
|
||||
You are applying proven testing patterns to write maintainable, reliable tests. These patterns help ensure tests are readable, focused, and trustworthy.
|
||||
|
||||
## Pattern Selection Guide
|
||||
|
||||
Use this to choose the right pattern for your situation:
|
||||
|
||||
- **Structuring a single test?** → Arrange-Act-Assert (AAA) or Given-When-Then
|
||||
- **Writing behavior/feature specs?** → Given-When-Then (BDD style)
|
||||
- **Repeating test setup data?** → Test Data Builders
|
||||
- **Many variations of complex objects?** → Object Mother
|
||||
- **Testing same logic with many inputs?** → Parameterized Tests
|
||||
- **Shared setup/teardown across tests?** → Test Fixtures
|
||||
- **Verifying a dependency was called?** → Spy
|
||||
- **Replacing an external dependency?** → Test Doubles (Stub / Mock / Fake)
|
||||
|
||||
---
|
||||
|
||||
## Pattern Combination Workflows
|
||||
|
||||
Patterns rarely stand alone — here's how to combine them for common scenarios:
|
||||
|
||||
**Unit tests (isolated logic):**
|
||||
Fixtures for setup → AAA structure → Stubs/Mocks for dependencies → Parameterized Tests for multiple input cases
|
||||
|
||||
**Integration tests (service + external dependencies):**
|
||||
Fixtures for setup → AAA structure → Fakes for external services (e.g. in-memory DB) → Spies to verify interaction points
|
||||
|
||||
**BDD / feature specs:**
|
||||
Given-When-Then → Object Mother or Test Data Builders for scenario data → Fakes for infrastructure
|
||||
|
||||
**High-variation logic (validators, calculators, formatters):**
|
||||
Parameterized Tests → Test Data Builders to construct each case → AAA structure within each case
|
||||
|
||||
---
|
||||
|
||||
## Core Pattern: Arrange-Act-Assert (AAA)
|
||||
|
||||
Structure every test with three distinct phases:
|
||||
@@ -89,11 +122,6 @@ const completedOrder = createTestOrder({ status: 'completed', total: 99.99 });
|
||||
const emptyOrder = createTestOrder({ items: [] });
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Reduces test setup boilerplate
|
||||
- Makes test intent clearer
|
||||
- Easy to create variations
|
||||
|
||||
## Pattern: Object Mother
|
||||
|
||||
Factory for complex test objects:
|
||||
@@ -186,12 +214,12 @@ it('should send notification on order completion', async () => {
|
||||
|
||||
Choose the right type:
|
||||
|
||||
| Type | Purpose | When to Use |
|
||||
|------|---------|-------------|
|
||||
| **Stub** | Returns canned data | Need predictable inputs |
|
||||
| **Mock** | Verifies interactions | Testing side effects |
|
||||
| **Spy** | Records calls | Partial mocking |
|
||||
| **Fake** | Working implementation | Need realistic behavior |
|
||||
| Type | When to Use |
|
||||
|------|-------------|
|
||||
| **Stub** | Need predictable, canned return values |
|
||||
| **Mock** | Need to assert a dependency was called correctly |
|
||||
| **Spy** | Partial mocking — observe calls on a real object |
|
||||
| **Fake** | Need a working lightweight substitute (e.g. in-memory DB) |
|
||||
|
||||
## Pattern: Test Isolation
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: "find-skills"
|
||||
description: "Discover and install skills from multiple marketplaces for AI coding agents"
|
||||
description: "Discovers, searches, and installs skills from multiple AI agent skill marketplaces (15,000+ skills) using the SkillKit CLI. Supports browsing official partner collections (Anthropic, Vercel, Supabase, Stripe, and more) and community repositories, searching by domain or technology, and installing specific skills from GitHub. Use when the user wants to find, browse, or install new agent skills, plugins, extensions, or add-ons; asks 'is there a skill for X' or 'find a skill for X'; wants to explore a skill store or marketplace; needs to extend agent capabilities in areas like React, testing, DevOps, security, or APIs; or says 'browse skills', 'search skill marketplace', 'install a skill', or 'what skills are available'."
|
||||
version: "1.0.0"
|
||||
tags: ["meta", "discovery", "marketplace", "skills"]
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user