📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: codify
|
||||
description: This skill should be used when implementing patterns as Claude Code components (skills, commands, hooks, agents), or when "codify", "capture workflow", "turn into a skill", or "make reusable" are mentioned. For pattern identification, see patterns skill.
|
||||
agent: analyst
|
||||
context: fork
|
||||
metadata:
|
||||
version: "1.3.0"
|
||||
related-skills:
|
||||
- patterns
|
||||
- claude-skills
|
||||
- claude-commands
|
||||
- claude-hooks
|
||||
- claude-agents
|
||||
---
|
||||
|
||||
# Codify
|
||||
|
||||
Identified pattern → component mapping → implementation.
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Spotting repeated behavior worth codifying
|
||||
- User explicitly wants to capture a workflow
|
||||
- Recognizing orchestration sequences in conversation
|
||||
- Identifying decision heuristics being applied
|
||||
|
||||
NOT for: one-off tasks, simple questions, well-documented existing patterns
|
||||
|
||||
</when_to_use>
|
||||
|
||||
<pattern_types>
|
||||
|
||||
| Type | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| Workflow | Multi-step sequences | Debug → Test → Fix → Verify |
|
||||
| Orchestration | Tool coordination | Git + Linear + PR automation |
|
||||
| Heuristic | Decision rules | "When X, do Y because Z" |
|
||||
|
||||
Workflows: Step-by-step processes with defined stages and transitions.
|
||||
Orchestration: Tool combinations that work together for a goal.
|
||||
Heuristics: Conditional logic and decision trees for common situations.
|
||||
|
||||
</pattern_types>
|
||||
|
||||
<component_mapping>
|
||||
|
||||
Match pattern type to implementation:
|
||||
|
||||
```text
|
||||
Is it a multi-step process with stages?
|
||||
├─ Yes → Does it need tool restrictions?
|
||||
│ ├─ Yes → Skill (with allowed_tools)
|
||||
│ └─ No → Skill
|
||||
└─ No → Is it a simple entry point?
|
||||
├─ Yes → Command (thin wrapper → Skill)
|
||||
└─ No → Is it autonomous/long-running?
|
||||
├─ Yes → Agent
|
||||
└─ No → Is it reactive to events?
|
||||
├─ Yes → Hook
|
||||
└─ No → Probably doesn't need codifying
|
||||
```
|
||||
|
||||
Composites:
|
||||
- Skill + Command: Skill holds logic, command provides entry point
|
||||
- Skill + Hook: Skill holds logic, hook triggers automatically
|
||||
- Agent + Skill: Agent orchestrates, skill provides methodology
|
||||
|
||||
</component_mapping>
|
||||
|
||||
<specification>
|
||||
|
||||
Pattern spec format (YAML):
|
||||
|
||||
```yaml
|
||||
name: pattern-name
|
||||
type: workflow | orchestration | heuristic
|
||||
trigger: when to apply
|
||||
stages: # workflow
|
||||
- name: stage-name
|
||||
actions: [...]
|
||||
exit_criteria: condition
|
||||
tools: # orchestration
|
||||
- tool: name
|
||||
role: purpose
|
||||
sequence: order
|
||||
rules: # heuristic
|
||||
- condition: when
|
||||
action: what
|
||||
rationale: why
|
||||
quality:
|
||||
specific: true | false
|
||||
repeatable: true | false
|
||||
valuable: true | false
|
||||
documented: true | false
|
||||
scoped: true | false
|
||||
```
|
||||
|
||||
All five quality checks must pass before codifying.
|
||||
|
||||
</specification>
|
||||
|
||||
<workflow>
|
||||
|
||||
1. Identify: Spot repeatable behavior in conversation
|
||||
- If hint/argument provided, focus analysis on that specific pattern
|
||||
- Otherwise scan for: workflows, orchestrations, and heuristics worth capturing
|
||||
- For deep analysis, load `outfitter:codebase-recon` skill and use `outfitter:patterns` techniques
|
||||
- Extract success, frustration, workflow, and request signals
|
||||
- Look for 3+ occurrences of similar behavior
|
||||
2. Classify: Workflow, Orchestration, or Heuristic?
|
||||
3. Map: Which component(s) should implement it?
|
||||
4. Specify: Document with pattern spec format
|
||||
5. Quality: Validate against SRVDS criteria
|
||||
6. Implement: Create the component(s)
|
||||
|
||||
Task stages:
|
||||
|
||||
```text
|
||||
- Identify { pattern description }
|
||||
- Classify { pattern type }
|
||||
- Map { component decision }
|
||||
- Specify { pattern name }
|
||||
- Implement { component type }
|
||||
```
|
||||
|
||||
</workflow>
|
||||
|
||||
<quality>
|
||||
|
||||
SRVDS criteria — all must pass:
|
||||
|
||||
| Check | Question | Red Flag |
|
||||
|-------|----------|----------|
|
||||
| Specific | Clear trigger + scope? | "Sometimes useful" |
|
||||
| Repeatable | Works across contexts? | One-off solution |
|
||||
| Valuable | Worth the overhead? | Saves < 5 minutes |
|
||||
| Documented | Can others understand? | Tribal knowledge |
|
||||
| Scoped | Single responsibility? | Kitchen sink |
|
||||
|
||||
Skip if: < 3 occurrences, context-dependent, simpler inline
|
||||
|
||||
</quality>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
- Premature abstraction: Codifying after first occurrence
|
||||
- Over-specification: 50-line spec for 5-line pattern
|
||||
- Wrong component: Hook when Skill needed, Agent when Command suffices
|
||||
- Missing trigger: Pattern exists but no clear activation
|
||||
- Scope creep: Pattern grows to handle edge cases
|
||||
|
||||
</anti_patterns>
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Identify pattern type before choosing component
|
||||
- Validate all SRVDS criteria
|
||||
- Start with minimal implementation
|
||||
- Document trigger conditions clearly
|
||||
- Test pattern in at least 2 contexts
|
||||
|
||||
NEVER:
|
||||
- Codify after single occurrence
|
||||
- Create Agent when Skill suffices
|
||||
- Skip quality validation
|
||||
- Implement without clear trigger
|
||||
- Add "might need later" features
|
||||
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
|
||||
- [pattern-types.md](references/pattern-types.md) — extended examples by type
|
||||
- [component-mapping.md](references/component-mapping.md) — decision tree details
|
||||
- [examples/](examples/) — captured pattern examples
|
||||
|
||||
**Identification vs Implementation**:
|
||||
- `patterns` skill identifies and documents patterns
|
||||
- This skill (`codify`) implements patterns as Claude Code components
|
||||
|
||||
Use `patterns` first to identify what's worth capturing. Use `codify` to turn identified patterns into skills, commands, hooks, or agents.
|
||||
|
||||
**Component skills** (loaded during implementation):
|
||||
- `claude-skills` — skill authoring
|
||||
- `claude-commands` — command authoring
|
||||
- `claude-hooks` — hook authoring
|
||||
- `claude-agents` — agent authoring
|
||||
|
||||
</references>
|
||||
@@ -0,0 +1,246 @@
|
||||
# Heuristic Pattern Example: PR Size Optimization
|
||||
|
||||
Demonstrates identifying, specifying, and implementing a heuristic pattern.
|
||||
|
||||
## Pattern Identification
|
||||
|
||||
<evidence>
|
||||
|
||||
User: "Our PRs keep getting stuck in review. When reviewed, feedback is often superficial."
|
||||
|
||||
Investigation:
|
||||
- Average PR size: 450 LOC, some exceeded 1,000 LOC
|
||||
- Large PRs (>300 LOC): 2.3 comments avg, 4.2 days to merge
|
||||
- Small PRs (<200 LOC): 8.7 comments avg, 1.1 days to merge
|
||||
|
||||
Pattern: PR size correlates with review quality and merge speed. Need decision rule for when to split.
|
||||
|
||||
</evidence>
|
||||
|
||||
<classification>
|
||||
|
||||
Type: Heuristic (decision rule with contextual exceptions)
|
||||
|
||||
Why not workflow: Not multi-step process, but a guideline
|
||||
Why not orchestration: Not coordinating tools, but providing framework
|
||||
|
||||
</classification>
|
||||
|
||||
## Pattern Specification
|
||||
|
||||
```yaml
|
||||
name: pr-size-optimization
|
||||
type: heuristic
|
||||
description: Decision framework for optimal PR size
|
||||
|
||||
condition: Preparing to create pull request
|
||||
action: Evaluate size, recommend splitting if over threshold
|
||||
|
||||
rationale: |
|
||||
Large PRs suffer from:
|
||||
- Reviewer fatigue
|
||||
- Superficial feedback
|
||||
- Longer time-to-merge
|
||||
- Higher defect rates
|
||||
|
||||
thresholds:
|
||||
ideal: 50-250 LOC
|
||||
acceptable: 250-300 LOC
|
||||
warning: 300-500 LOC
|
||||
must_split: 500+ LOC
|
||||
|
||||
calculation: |
|
||||
Effective LOC = Total - Mechanical changes
|
||||
|
||||
Mechanical (exclude):
|
||||
- Lockfiles (package-lock.json, Cargo.lock)
|
||||
- Formatting-only changes
|
||||
- Batch renames
|
||||
- Code moves without logic changes
|
||||
- Auto-generated schemas
|
||||
|
||||
rules:
|
||||
- condition: LOC < 50
|
||||
severity: info
|
||||
action: Consider if PR is complete
|
||||
|
||||
- condition: LOC 50-250
|
||||
severity: success
|
||||
action: Proceed
|
||||
|
||||
- condition: LOC 250-300
|
||||
severity: warning
|
||||
action: Consider splitting if natural boundaries exist
|
||||
|
||||
- condition: LOC 300-500
|
||||
severity: warning
|
||||
action: Strongly recommend splitting
|
||||
|
||||
- condition: LOC > 500
|
||||
severity: error
|
||||
action: Must split unless exception
|
||||
|
||||
exceptions:
|
||||
mechanical_changes:
|
||||
description: Auto-generated or formatting-only
|
||||
action: Isolate in separate PR, mark as mechanical
|
||||
|
||||
emergency_hotfix:
|
||||
description: Production incident requiring immediate fix
|
||||
action: Proceed, plan follow-up split
|
||||
|
||||
approved_exception:
|
||||
description: Team lead approves for specific reason
|
||||
action: Document exception in PR description
|
||||
|
||||
splitting_strategies:
|
||||
logical_stages: Schema → Backend → Frontend → Tests
|
||||
commit_boundaries: Each commit becomes PR in stack
|
||||
refactor_vs_feature: Preparatory refactoring separate from feature
|
||||
by_component: Separate PRs per service/module
|
||||
```
|
||||
|
||||
## Component Recommendation
|
||||
|
||||
<analysis>
|
||||
|
||||
Invocation: User-invoked (manual check) or event-triggered (pre-push)
|
||||
Automation: Partially — LOC counting automated, split decision requires judgment
|
||||
|
||||
Decision: **SKILL + HOOK** (composite)
|
||||
|
||||
</analysis>
|
||||
|
||||
<rationale>
|
||||
|
||||
SKILL because:
|
||||
- Provides guidance on thresholds
|
||||
- Explains rationale for limits
|
||||
- Teaches splitting strategies
|
||||
- Requires judgment on split boundaries
|
||||
|
||||
HOOK because:
|
||||
- Automatically checks on pre-push
|
||||
- Warns if over threshold
|
||||
- Can block (configurable)
|
||||
- Immediate feedback
|
||||
|
||||
Not just COMMAND: Requires teaching beyond execution
|
||||
Not AGENT: General engineering, not specialized
|
||||
|
||||
</rationale>
|
||||
|
||||
<composite>
|
||||
|
||||
SKILL: pr-size-optimization — guidance and strategies
|
||||
HOOK: pre-push — automatic validation
|
||||
COMMAND: /check-pr-size — manual check during development
|
||||
|
||||
</composite>
|
||||
|
||||
## Implementation Sketch
|
||||
|
||||
### File Structure
|
||||
|
||||
```text
|
||||
skills/
|
||||
pr-size-optimization/
|
||||
SKILL.md
|
||||
examples/
|
||||
splitting-strategies.md
|
||||
exceptions.md
|
||||
|
||||
hooks/
|
||||
pre-push/
|
||||
check-pr-size.sh
|
||||
|
||||
commands/
|
||||
check-pr-size.md
|
||||
```
|
||||
|
||||
### Pre-push Hook
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
||||
BASE="main"
|
||||
|
||||
EFFECTIVE_LOC=$(./scripts/pr-size/count-effective-loc.sh "$BASE" "$BRANCH")
|
||||
|
||||
echo "PR size check: $EFFECTIVE_LOC effective LOC"
|
||||
|
||||
IDEAL=250; WARNING=300; ERROR=500
|
||||
|
||||
if (( EFFECTIVE_LOC <= IDEAL )); then
|
||||
echo "✅ PR size ideal for review"
|
||||
elif (( EFFECTIVE_LOC <= WARNING )); then
|
||||
echo "⚠️ Acceptable, consider splitting (${EFFECTIVE_LOC}/${WARNING} LOC)"
|
||||
elif (( EFFECTIVE_LOC <= ERROR )); then
|
||||
echo "⚠️ Large - strongly recommend splitting"
|
||||
[[ "${PR_SIZE_STRICT:-false}" == "true" ]] && exit 1
|
||||
else
|
||||
echo "🛑 Too large (${EFFECTIVE_LOC} LOC, limit: ${ERROR})"
|
||||
echo " Must split unless exceptional circumstances"
|
||||
[[ "${PR_SIZE_OVERRIDE:-false}" != "true" ]] && exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Manual Command
|
||||
|
||||
```bash
|
||||
$ /check-pr-size
|
||||
|
||||
Analyzing PR size...
|
||||
|
||||
Total changed lines: 487
|
||||
Mechanical changes: 143 (package-lock.json)
|
||||
Effective LOC: 344
|
||||
|
||||
Status: ⚠️ LARGE - Recommend splitting
|
||||
|
||||
Suggested split points:
|
||||
1. After commit "Add user model" (123 LOC)
|
||||
2. After commit "Add auth endpoints" (221 LOC)
|
||||
```
|
||||
|
||||
## Splitting Example
|
||||
|
||||
**Before** (487 LOC):
|
||||
|
||||
```text
|
||||
feat: add user authentication
|
||||
- Add user model and schema
|
||||
- Add auth endpoints
|
||||
- Add session management
|
||||
- Add login UI
|
||||
```
|
||||
|
||||
**After** (stacked PRs):
|
||||
|
||||
```text
|
||||
PR #1: feat: add user model (123 LOC)
|
||||
PR #2: feat: add auth endpoints (108 LOC) ← based on #1
|
||||
PR #3: feat: add session management (89 LOC) ← based on #2
|
||||
PR #4: feat: add login UI (124 LOC) ← based on #3
|
||||
```
|
||||
|
||||
Using Graphite:
|
||||
|
||||
```bash
|
||||
gt create -m "feat: add user model"
|
||||
gt create -m "feat: add auth endpoints"
|
||||
gt create -m "feat: add session management"
|
||||
gt create -m "feat: add login UI"
|
||||
gt submit --stack
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Before | Target |
|
||||
|--------|--------|--------|
|
||||
| Average PR size | 450 LOC | <250 LOC |
|
||||
| Review time | 3.8 days | <1.5 days |
|
||||
| Comments/PR | 3.2 | >6.0 |
|
||||
| Defect escape rate | 12% | <5% |
|
||||
@@ -0,0 +1,220 @@
|
||||
# Orchestration Pattern Example: Git + Linear Integration
|
||||
|
||||
Demonstrates identifying, specifying, and implementing an orchestration pattern.
|
||||
|
||||
## Pattern Identification
|
||||
|
||||
<evidence>
|
||||
|
||||
User: "Every time I commit, I manually update Linear with the commit SHA and branch. Can we automate this?"
|
||||
|
||||
Analysis:
|
||||
- User has git workflow (commits, branches, PRs)
|
||||
- User tracks work in Linear (issues, status)
|
||||
- Manual coordination is time-consuming and error-prone
|
||||
|
||||
Pattern: Tool orchestration — coordinating git with Linear based on commit messages.
|
||||
|
||||
</evidence>
|
||||
|
||||
<classification>
|
||||
|
||||
Type: Orchestration (coordinating multiple external tools)
|
||||
|
||||
Why not workflow: Not multi-stage, but ongoing event-driven coordination
|
||||
Why not heuristic: Not a decision rule, but automated synchronization
|
||||
|
||||
</classification>
|
||||
|
||||
## Pattern Specification
|
||||
|
||||
```yaml
|
||||
name: git-linear-sync
|
||||
type: orchestration
|
||||
description: Synchronize git commits with Linear issues automatically
|
||||
|
||||
tools:
|
||||
- name: Git
|
||||
purpose: Version control, commit history
|
||||
access: Local git commands
|
||||
|
||||
- name: Linear API
|
||||
purpose: Issue tracking, status updates
|
||||
access: GraphQL with auth
|
||||
|
||||
- name: Pattern Matching
|
||||
purpose: Extract issue IDs from commits
|
||||
access: String parsing
|
||||
|
||||
coordination:
|
||||
- Extract Linear issue IDs from commit messages (ABC-123)
|
||||
- Query Linear API for issue details
|
||||
- Post commit info to Linear as comment
|
||||
- Update issue status based on keywords
|
||||
- Link commit SHA to issue
|
||||
|
||||
commit_format: |
|
||||
feat: implement auth [ABC-123]
|
||||
ABC-123: fix password reset
|
||||
|
||||
keywords:
|
||||
closes: [closes, fixes, resolves]
|
||||
starts: [starts, wip, begin]
|
||||
updates: [updates, relates to, ref]
|
||||
|
||||
status_mapping:
|
||||
closes: Done
|
||||
starts: In Progress
|
||||
updates: In Progress (if Backlog/Todo)
|
||||
|
||||
triggers:
|
||||
- post-commit: Update after each commit
|
||||
- pre-push: Batch update for multiple commits
|
||||
|
||||
error_handling:
|
||||
- API unreachable: Log error, don't block commit
|
||||
- Issue not found: Log warning
|
||||
- Multiple issue IDs: Update all
|
||||
- Retry: 3 attempts with exponential backoff
|
||||
```
|
||||
|
||||
## Component Recommendation
|
||||
|
||||
<analysis>
|
||||
|
||||
Invocation: Event-triggered (git hooks)
|
||||
Automation: Fully automatable (pattern matching, API calls)
|
||||
Behavior modification: Yes (augments commits with Linear updates)
|
||||
|
||||
Decision: **HOOK**
|
||||
|
||||
</analysis>
|
||||
|
||||
<rationale>
|
||||
|
||||
HOOK because:
|
||||
- Event-triggered (post-commit, pre-push)
|
||||
- Fully automatable, no human judgment
|
||||
- Augments git operations automatically
|
||||
- Should run without user action
|
||||
|
||||
Not COMMAND: Should run automatically
|
||||
Not SKILL: No guidance needed
|
||||
Not AGENT: No expertise required
|
||||
|
||||
</rationale>
|
||||
|
||||
<composite>
|
||||
|
||||
COMMAND: `/linear-sync` — manually trigger for backfilling
|
||||
SKILL: linear-workflow — guidance on commit conventions
|
||||
|
||||
</composite>
|
||||
|
||||
## Implementation Sketch
|
||||
|
||||
### File Structure
|
||||
|
||||
```text
|
||||
hooks/
|
||||
post-commit/
|
||||
linear-sync.sh
|
||||
pre-push/
|
||||
linear-batch-sync.sh
|
||||
|
||||
scripts/
|
||||
linear/
|
||||
extract-issues.sh
|
||||
update-linear.sh
|
||||
|
||||
commands/
|
||||
linear-sync.md
|
||||
```
|
||||
|
||||
### Hook Implementation
|
||||
|
||||
**post-commit hook**:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Check API key
|
||||
if [[ -z "${LINEAR_API_KEY:-}" ]]; then
|
||||
echo "Warning: LINEAR_API_KEY not set, skipping sync"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Get commit info
|
||||
COMMIT_SHA=$(git rev-parse HEAD)
|
||||
COMMIT_MSG=$(git log -1 --pretty=%B "$COMMIT_SHA")
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
||||
|
||||
# Extract issue IDs (ABC-123)
|
||||
ISSUE_IDS=$(echo "$COMMIT_MSG" | grep -oE '[A-Z]+-[0-9]+' || true)
|
||||
|
||||
[[ -z "$ISSUE_IDS" ]] && exit 0
|
||||
|
||||
# Determine action from keywords
|
||||
ACTION="update"
|
||||
echo "$COMMIT_MSG" | grep -qiE '\b(closes|fixes|resolves)\b' && ACTION="close"
|
||||
echo "$COMMIT_MSG" | grep -qiE '\b(starts|wip|begin)\b' && ACTION="start"
|
||||
|
||||
# Update each issue
|
||||
while IFS= read -r ISSUE_ID; do
|
||||
./scripts/linear/update-linear.sh \
|
||||
--issue-id "$ISSUE_ID" \
|
||||
--commit-sha "$COMMIT_SHA" \
|
||||
--branch "$BRANCH" \
|
||||
--action "$ACTION"
|
||||
done <<< "$ISSUE_IDS"
|
||||
```
|
||||
|
||||
### Manual Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Manually sync commits with Linear
|
||||
---
|
||||
|
||||
# /linear-sync
|
||||
|
||||
Sync existing commits with Linear issues.
|
||||
|
||||
Usage:
|
||||
- `/linear-sync` — sync last 5 commits
|
||||
- `/linear-sync main..feature` — sync range
|
||||
- `/linear-sync --dry-run` — preview changes
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Single issue
|
||||
git commit -m "ABC-123: test commit"
|
||||
# → Comment added to ABC-123
|
||||
|
||||
# Multiple issues
|
||||
git commit -m "ABC-123 ABC-456: multi-issue"
|
||||
# → Comments on both
|
||||
|
||||
# Closes keyword
|
||||
git commit -m "Closes ABC-123: fix bug"
|
||||
# → ABC-123 moved to Done
|
||||
|
||||
# No issue ID
|
||||
git commit -m "refactor: clean up"
|
||||
# → No API calls, silent success
|
||||
|
||||
# API down
|
||||
LINEAR_API_KEY="invalid" git commit -m "ABC-123: test"
|
||||
# → Warning logged, commit succeeds
|
||||
```
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Before | After |
|
||||
|--------|--------|-------|
|
||||
| Time per commit | 2–3 min manual | 0 sec |
|
||||
| Update accuracy | ~85% (human error) | ~98% |
|
||||
| Commit traceability | Often incomplete | 100% linked |
|
||||
@@ -0,0 +1,191 @@
|
||||
# Workflow Pattern Example: Systematic Debugging
|
||||
|
||||
Demonstrates identifying, specifying, and implementing a workflow pattern.
|
||||
|
||||
## Pattern Identification
|
||||
|
||||
<evidence>
|
||||
|
||||
User: "I have a bug where users can't log in after password reset."
|
||||
|
||||
Agent flow:
|
||||
1. Asked for error message and reproduction steps
|
||||
2. Created minimal reproduction case, confirmed bug
|
||||
3. Added logging, inspected state, reviewed recent changes
|
||||
4. Identified root cause: password hash using wrong algorithm
|
||||
5. Implemented fix, added regression test
|
||||
6. Bug resolved
|
||||
|
||||
Pattern: Systematic debugging - structured investigation, not trial-and-error.
|
||||
|
||||
</evidence>
|
||||
|
||||
<classification>
|
||||
|
||||
Type: Workflow (multi-step sequence with clear stages)
|
||||
|
||||
Why not orchestration: Doesn't primarily coordinate external tools
|
||||
Why not heuristic: Not a decision rule, but a procedural process
|
||||
|
||||
</classification>
|
||||
|
||||
## Pattern Specification
|
||||
|
||||
```yaml
|
||||
name: systematic-debugging
|
||||
type: workflow
|
||||
description: Structured root cause investigation
|
||||
|
||||
stages:
|
||||
- name: Reproduction
|
||||
goal: Create reliable, minimal reproduction
|
||||
actions:
|
||||
- Gather error messages, logs, stack traces
|
||||
- Document exact steps to trigger
|
||||
- Reduce to minimal reproduction case
|
||||
- Verify reproducibility
|
||||
exit_criteria: Can trigger bug on demand
|
||||
|
||||
- name: Investigation
|
||||
goal: Form hypothesis about root cause
|
||||
actions:
|
||||
- Add logging at suspected points
|
||||
- Use debugger to inspect state
|
||||
- Review recent changes (git log, blame)
|
||||
- Check related issues/PRs
|
||||
exit_criteria: Specific, testable hypothesis
|
||||
|
||||
- name: Validation
|
||||
goal: Confirm fix works without regressions
|
||||
actions:
|
||||
- Implement minimal fix
|
||||
- Test against reproduction case
|
||||
- Run full test suite
|
||||
exit_criteria: Fix resolves bug, no new failures
|
||||
|
||||
- name: Prevention
|
||||
goal: Prevent future recurrence
|
||||
actions:
|
||||
- Add regression test
|
||||
- Document root cause in commit
|
||||
exit_criteria: Test would fail if bug reoccurs
|
||||
|
||||
quality_criteria:
|
||||
- Each stage has clear outputs
|
||||
- Don't skip reproduction for "fixes"
|
||||
- Don't accept fixes without root cause
|
||||
- Always add regression test
|
||||
|
||||
anti_patterns:
|
||||
- Random trial-and-error
|
||||
- Fixing symptoms instead of root cause
|
||||
- No regression tests
|
||||
- Incomplete reproduction
|
||||
```
|
||||
|
||||
## Component Recommendation
|
||||
|
||||
<analysis>
|
||||
|
||||
Invocation: User-triggered (bug report, debugging request)
|
||||
Automation: Cannot be fully automated (requires judgment)
|
||||
Domain Expertise: General software engineering
|
||||
|
||||
Decision: **SKILL**
|
||||
|
||||
</analysis>
|
||||
|
||||
<rationale>
|
||||
|
||||
SKILL because:
|
||||
- User invokes when encountering bugs
|
||||
- Requires judgment (hypothesis formation, fix validation)
|
||||
- Not specialized domain (any engineer should debug)
|
||||
- Benefits from progressive disclosure
|
||||
|
||||
Not COMMAND: Can't be scripted, requires contextual decisions
|
||||
Not AGENT: General engineering, not specialized domain
|
||||
Not HOOK: User-invoked, not event-triggered
|
||||
|
||||
</rationale>
|
||||
|
||||
<composite>
|
||||
|
||||
COMMAND: `/reproduce-bug` — automate running reproduction steps
|
||||
COMMAND: `/run-regression-tests` — run tests related to bug area
|
||||
HOOK: post-fix — warn if no regression test added
|
||||
|
||||
</composite>
|
||||
|
||||
## Implementation Sketch
|
||||
|
||||
### File Structure
|
||||
|
||||
```text
|
||||
skills/
|
||||
systematic-debugging/
|
||||
SKILL.md
|
||||
examples/
|
||||
auth-bug.md
|
||||
race-condition.md
|
||||
references/
|
||||
debugging-tools.md
|
||||
common-patterns.md
|
||||
```
|
||||
|
||||
### Key Sections
|
||||
|
||||
**Quick Start**:
|
||||
1. Reproduce: Create minimal, reliable reproduction
|
||||
2. Investigate: Form hypothesis using logging/debugging
|
||||
3. Validate: Implement fix, verify no regressions
|
||||
4. Prevent: Add regression test, document learnings
|
||||
|
||||
**Hypothesis Documentation**:
|
||||
|
||||
```text
|
||||
Hypothesis: Password reset uses bcrypt, login uses SHA-256,
|
||||
causing hashes to never match.
|
||||
|
||||
Evidence:
|
||||
- resetPassword() calls bcrypt.hash()
|
||||
- login() calls crypto.createHash('sha256')
|
||||
- Logged hashes have different formats
|
||||
|
||||
Test: Change login to use bcrypt.compare()
|
||||
```
|
||||
|
||||
**Regression Test**:
|
||||
|
||||
```typescript
|
||||
it('allows login with new password after reset', async () => {
|
||||
const user = await createTestUser('test@example.com');
|
||||
await resetPassword(user.email);
|
||||
const newPassword = getLatestResetToken(user.email);
|
||||
|
||||
const result = await login(user.email, newPassword);
|
||||
expect(result.success).toBe(true);
|
||||
});
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Random trial and error**:
|
||||
- ✗ "Let me try changing this and see"
|
||||
- ✓ "Based on logs, I hypothesize X. Let me test that."
|
||||
|
||||
**Fixing symptoms**:
|
||||
- ✗ "Skip password verification for reset users"
|
||||
- ✓ "Fix root cause: inconsistent hashing algorithms"
|
||||
|
||||
**No regression test**:
|
||||
- ✗ Fix, commit, move on
|
||||
- ✓ Add test that fails if bug reoccurs
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Before | After |
|
||||
|--------|--------|-------|
|
||||
| Time to resolution | Varies (30min–5hr) | Consistent (1–2hr) |
|
||||
| Regression rate | ~15% | <5% |
|
||||
| First-fix success | ~40% | ~75% |
|
||||
@@ -0,0 +1,230 @@
|
||||
# Component Mapping Reference
|
||||
|
||||
Detailed decision logic for mapping patterns to Claude Code components.
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```text
|
||||
START: Pattern Identified
|
||||
│
|
||||
├── USER-INVOKED?
|
||||
│ │
|
||||
│ ├── YES → Requires domain expertise throughout?
|
||||
│ │ │
|
||||
│ │ ├── YES → AGENT
|
||||
│ │ │ (specialized system prompt, deep knowledge)
|
||||
│ │ │
|
||||
│ │ └── NO → Fully automatable?
|
||||
│ │ │
|
||||
│ │ ├── YES → COMMAND
|
||||
│ │ │ (script-based, deterministic)
|
||||
│ │ │
|
||||
│ │ └── NO → SKILL
|
||||
│ │ (structured guidance, judgment needed)
|
||||
│ │
|
||||
│ └── NO (EVENT-TRIGGERED) → Modifies behavior?
|
||||
│ │
|
||||
│ ├── YES → HOOK
|
||||
│ │ (can block/augment operations)
|
||||
│ │
|
||||
│ └── NO → Question if needed
|
||||
```
|
||||
|
||||
## Examples by Decision Path
|
||||
|
||||
<example name="tdd-workflow">
|
||||
Path: User-invoked → No domain expertise → Not fully automatable → **SKILL**
|
||||
|
||||
Why not COMMAND: Requires judgment on test design, refactoring decisions
|
||||
Why not AGENT: General software practice, not specialized domain
|
||||
|
||||
Composite: Add `/run-tdd-cycle` COMMAND for mechanical test execution
|
||||
</example>
|
||||
|
||||
<example name="security-audit">
|
||||
Path: User-invoked → Requires domain expertise → **AGENT**
|
||||
|
||||
Why AGENT: Security requires deep specialized knowledge for every decision
|
||||
Why not SKILL: Can't encode all security judgment in progressive disclosure
|
||||
|
||||
Composite: AGENT can use vulnerability-scanning SKILL, `/check-deps` COMMAND
|
||||
</example>
|
||||
|
||||
<example name="code-formatting">
|
||||
Path: User-invoked → No expertise → Fully automatable → **COMMAND**
|
||||
|
||||
Why COMMAND: Deterministic, rule-based, no judgment needed
|
||||
Why not SKILL: No guidance needed, just run the tool
|
||||
|
||||
Composite: Add pre-commit HOOK for automatic formatting
|
||||
</example>
|
||||
|
||||
<example name="pre-commit-validation">
|
||||
Path: Event-triggered → Modifies behavior → **HOOK**
|
||||
|
||||
Why HOOK: Automatically runs on git event, can block commit
|
||||
Implementation: `pre-commit` hook runs validation script
|
||||
</example>
|
||||
|
||||
<example name="git-linear-integration">
|
||||
Path: Event-triggered → Modifies behavior → **HOOK**
|
||||
|
||||
Why HOOK: Triggered by commit, augments with Linear updates
|
||||
No user action required, happens in normal git workflow
|
||||
</example>
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Manual + Automated
|
||||
|
||||
Running tests: both manual and CI use cases
|
||||
|
||||
```text
|
||||
COMMAND: /run-tests
|
||||
User-invoked, allows parameters (--watch, --coverage)
|
||||
|
||||
HOOK: pre-push
|
||||
Automatically runs tests, blocks on failure
|
||||
Calls same script as COMMAND
|
||||
```
|
||||
|
||||
### Guidance + Enforcement
|
||||
|
||||
PR size limits: suggest vs block
|
||||
|
||||
```text
|
||||
SKILL: pr-workflow
|
||||
Provides guidance on optimal size
|
||||
Helps plan PR stack structure
|
||||
|
||||
HOOK: pre-push (optional)
|
||||
Warns or blocks on threshold
|
||||
User configures hard vs soft limit
|
||||
```
|
||||
|
||||
### Encodable Expertise
|
||||
|
||||
TypeScript type design: expert knowledge that can be captured
|
||||
|
||||
```text
|
||||
SKILL (not AGENT) because:
|
||||
- Don't need specialized prompt for every decision
|
||||
- Expertise can be progressively disclosed
|
||||
- Works in general engineering context
|
||||
|
||||
Use AGENT when:
|
||||
- Type-level programming (mapped, conditional, template types)
|
||||
- Designing complex type system for library
|
||||
- Every interaction requires type theory
|
||||
```
|
||||
|
||||
### Mixed Automation
|
||||
|
||||
Feature development: some steps automatable, some need judgment
|
||||
|
||||
```text
|
||||
SKILL: feature-development
|
||||
Overall workflow guidance
|
||||
Design decisions, quality criteria
|
||||
|
||||
COMMANDs orchestrated by SKILL:
|
||||
- /create-feature-branch
|
||||
- /run-tests
|
||||
- /generate-pr-description
|
||||
```
|
||||
|
||||
## Selection Matrix
|
||||
|
||||
| Criteria | Skill | Command | Agent | Hook |
|
||||
|----------|-------|---------|-------|------|
|
||||
| User-invoked | ✓ | ✓ | ✓ | ✗ |
|
||||
| Event-triggered | ✗ | ✗ | ✗ | ✓ |
|
||||
| Requires judgment | ✓ | ✗ | ✓ | ✗ |
|
||||
| Fully automatable | ✗ | ✓ | ✗ | ✓ |
|
||||
| Domain expertise | ✗ | ✗ | ✓ | ✗ |
|
||||
| Progressive disclosure | ✓ | ✗ | rarely | ✗ |
|
||||
| Can block operations | ✗ | can fail | ✗ | ✓ (pre-*) |
|
||||
|
||||
## Composite Patterns
|
||||
|
||||
**SKILL + COMMAND**: Workflow has guidance + automation needs
|
||||
- SKILL provides strategy, COMMAND handles execution
|
||||
- Example: TDD skill + `/run-tests`
|
||||
|
||||
**SKILL + HOOK**: Guidance reinforced with automated checks
|
||||
- SKILL teaches best practices, HOOK enforces them
|
||||
- Example: PR workflow + pre-push size validation
|
||||
|
||||
**AGENT + SKILL**: Expert needs extended capabilities
|
||||
- AGENT embodies expertise, SKILLs extend it
|
||||
- Example: Security agent + vulnerability scanning skill
|
||||
|
||||
**COMMAND + HOOK**: Same operation, manual and automatic
|
||||
- COMMAND for manual, HOOK for automation
|
||||
- Example: `/format-code` + pre-commit format hook
|
||||
|
||||
**Multi-component (SKILL + COMMAND + HOOK)**: Complete workflow
|
||||
- SKILL guides, COMMAND automates, HOOK enforces
|
||||
- Example: Testing (strategy skill + /run-tests + pre-push coverage)
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
**Creating AGENT for non-expert work**
|
||||
|
||||
```text
|
||||
✗ file-organizer-agent
|
||||
✓ COMMAND for organization, SKILL for strategy
|
||||
```
|
||||
|
||||
**Using SKILL when COMMAND suffices**
|
||||
|
||||
```text
|
||||
✗ run-prettier-skill (no guidance needed)
|
||||
✓ COMMAND /format
|
||||
```
|
||||
|
||||
**Creating HOOK for user-driven action**
|
||||
|
||||
```text
|
||||
✗ on-user-request hook
|
||||
✓ COMMAND or SKILL
|
||||
```
|
||||
|
||||
**Encoding expertise in COMMAND**
|
||||
|
||||
```text
|
||||
✗ grep-based security check
|
||||
✓ AGENT for real review, or external scanning tool
|
||||
```
|
||||
|
||||
**Over-compositing**
|
||||
|
||||
```text
|
||||
✗ SKILL + COMMAND + HOOK + AGENT for simple linting
|
||||
✓ COMMAND, optionally HOOK for pre-commit
|
||||
```
|
||||
|
||||
## Decision Checklist
|
||||
|
||||
1. **Invocation**: How triggered?
|
||||
- User request → SKILL/COMMAND/AGENT
|
||||
- Event → HOOK
|
||||
- Both → COMMAND + HOOK
|
||||
|
||||
2. **Automation**: Fully automatable?
|
||||
- Yes, no judgment → COMMAND
|
||||
- No, requires decisions → SKILL or AGENT
|
||||
|
||||
3. **Expertise**: Specialized domain knowledge?
|
||||
- Yes, for every step → AGENT
|
||||
- Yes, but encodable → SKILL
|
||||
- No → SKILL or COMMAND
|
||||
|
||||
4. **Behavior**: Modifies agent behavior or enforces rules?
|
||||
- Yes (event-triggered) → HOOK
|
||||
- No → SKILL/COMMAND/AGENT
|
||||
|
||||
5. **Value**: Saves time or reduces errors?
|
||||
- Yes → Worth capturing
|
||||
- Marginal → Question if needed
|
||||
- No → Don't create component
|
||||
@@ -0,0 +1,525 @@
|
||||
# Pattern Types Reference
|
||||
|
||||
Extended examples, anti-patterns, and guidance for complex pattern scenarios.
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
Multi-step sequences with defined stages and transitions.
|
||||
|
||||
### Examples
|
||||
|
||||
<example name="tdd-workflow">
|
||||
```yaml
|
||||
name: tdd-workflow
|
||||
type: workflow
|
||||
description: Red-Green-Refactor cycle
|
||||
|
||||
stages:
|
||||
- name: Red
|
||||
actions: [understand requirement, write failing test, confirm failure]
|
||||
exit_criteria: test fails with clear assertion
|
||||
|
||||
- name: Green
|
||||
actions: [write minimal implementation, run until pass]
|
||||
exit_criteria: test passes
|
||||
|
||||
- name: Refactor
|
||||
actions: [improve quality, extract duplicates, re-run tests]
|
||||
exit_criteria: clean code, all tests pass
|
||||
|
||||
triggers:
|
||||
- implementing new feature
|
||||
- fixing bug with test coverage
|
||||
|
||||
```
|
||||
|
||||
Component: Skill (requires judgment on test design)
|
||||
Composite: Add `/tdd` command for scaffolding
|
||||
</example>
|
||||
|
||||
<example name="systematic-debugging">
|
||||
```yaml
|
||||
name: systematic-debugging
|
||||
type: workflow
|
||||
description: Structured root cause investigation
|
||||
|
||||
stages:
|
||||
- name: Reproduction
|
||||
actions: [create minimal case, document steps, confirm consistency]
|
||||
exit_criteria: reproducible steps
|
||||
|
||||
- name: Investigation
|
||||
actions: [add logging, use debugger, check recent changes]
|
||||
exit_criteria: root cause hypothesis
|
||||
|
||||
- name: Validation
|
||||
actions: [test hypothesis, verify fix, check regressions]
|
||||
exit_criteria: confirmed fix
|
||||
|
||||
- name: Prevention
|
||||
actions: [add regression test, document root cause]
|
||||
exit_criteria: test coverage + documentation
|
||||
|
||||
triggers:
|
||||
- bug report received
|
||||
- unexpected behavior
|
||||
- CI test failure
|
||||
```
|
||||
|
||||
Component: Skill (requires investigative judgment)
|
||||
Composite: Add Hook to enforce regression test
|
||||
</example>
|
||||
|
||||
<example name="pr-review">
|
||||
```yaml
|
||||
name: pr-review
|
||||
type: workflow
|
||||
description: Comprehensive PR review process
|
||||
|
||||
stages:
|
||||
- name: Context
|
||||
actions: [read description, understand problem, review discussion]
|
||||
exit_criteria: clear understanding of intent
|
||||
|
||||
- name: Code Review
|
||||
actions: [check correctness, verify tests, assess readability]
|
||||
exit_criteria: quality assessment
|
||||
|
||||
- name: Testing
|
||||
actions: [checkout locally, run tests, manual testing]
|
||||
exit_criteria: confidence in implementation
|
||||
|
||||
- name: Feedback
|
||||
actions: [specific comments, highlight positives, approve/request changes]
|
||||
exit_criteria: review decision
|
||||
|
||||
triggers:
|
||||
- PR ready for review
|
||||
- review requested
|
||||
|
||||
```
|
||||
|
||||
Component: Skill (requires judgment on code quality)
|
||||
Composite: Add Command `/code-review` for automated checks
|
||||
</example>
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
Too granular:
|
||||
```yaml
|
||||
# BAD
|
||||
steps:
|
||||
- open terminal
|
||||
- type git status
|
||||
- press enter
|
||||
```
|
||||
|
||||
Too vague:
|
||||
|
||||
```yaml
|
||||
# BAD
|
||||
steps:
|
||||
- understand the problem
|
||||
- write good code
|
||||
- test it
|
||||
```
|
||||
|
||||
Tool-specific instead of outcome-focused:
|
||||
|
||||
```yaml
|
||||
# BAD
|
||||
steps:
|
||||
- Use Jest to write tests
|
||||
|
||||
# GOOD
|
||||
steps:
|
||||
- Write tests that verify behavior
|
||||
```
|
||||
|
||||
### Hybrid Example
|
||||
|
||||
Feature development with stacked PRs combines workflow + orchestration:
|
||||
|
||||
```yaml
|
||||
name: stacked-feature-development
|
||||
type: workflow
|
||||
orchestration_aspects:
|
||||
- Git branch management
|
||||
- GitHub PR creation
|
||||
- Stack synchronization
|
||||
|
||||
stages:
|
||||
- name: Planning
|
||||
actions: [break into commits, define stack]
|
||||
orchestration: [gt init]
|
||||
|
||||
- name: Implementation
|
||||
actions: [implement unit, write tests]
|
||||
orchestration: [git add, gt create]
|
||||
|
||||
- name: Submission
|
||||
orchestration: [gt submit --stack]
|
||||
```
|
||||
|
||||
Component: Skill + Hook (enforce stack constraints)
|
||||
|
||||
---
|
||||
|
||||
## Orchestration Patterns
|
||||
|
||||
Tool coordination for achieving complex goals.
|
||||
|
||||
### Examples
|
||||
|
||||
<example name="multi-service-deploy">
|
||||
```yaml
|
||||
name: multi-service-deploy
|
||||
type: orchestration
|
||||
description: Deploy services with dependency ordering
|
||||
|
||||
tools:
|
||||
- tool: Docker
|
||||
role: container management
|
||||
- tool: Kubernetes
|
||||
role: orchestration
|
||||
- tool: Health endpoints
|
||||
role: verification
|
||||
|
||||
sequence:
|
||||
1. Build container images
|
||||
2. Push to registry
|
||||
3. Deploy database migrations
|
||||
4. Wait for database health
|
||||
5. Deploy backend
|
||||
6. Wait for backend health
|
||||
7. Deploy frontend
|
||||
8. Verify end-to-end
|
||||
|
||||
rollback: Revert in reverse dependency order
|
||||
|
||||
```
|
||||
|
||||
Component: Skill (manual with judgment) or Command (if automated)
|
||||
</example>
|
||||
|
||||
<example name="git-linear-integration">
|
||||
```yaml
|
||||
name: git-linear-integration
|
||||
type: orchestration
|
||||
description: Update Linear from git commits
|
||||
|
||||
tools:
|
||||
- tool: Bash
|
||||
role: git commands
|
||||
- tool: Linear API
|
||||
role: issue updates
|
||||
- tool: Grep
|
||||
role: extract issue IDs
|
||||
|
||||
sequence:
|
||||
1. Extract issue IDs from commit (ABC-123)
|
||||
2. Query Linear for issue details
|
||||
3. Post commit SHA as comment
|
||||
4. Update issue status on keywords
|
||||
|
||||
triggers:
|
||||
- post-commit hook
|
||||
- pre-push hook (batch)
|
||||
```
|
||||
|
||||
Component: Hook (event-driven, automated)
|
||||
</example>
|
||||
|
||||
<example name="parallel-test-aggregation">
|
||||
```yaml
|
||||
name: parallel-test-aggregation
|
||||
type: orchestration
|
||||
description: Run tests in parallel, aggregate results
|
||||
|
||||
tools:
|
||||
- tool: Bash
|
||||
role: process management
|
||||
- tool: Test runner
|
||||
role: execution
|
||||
- tool: JSON parser
|
||||
role: result aggregation
|
||||
|
||||
coordination:
|
||||
- Split tests into groups
|
||||
- Execute in parallel
|
||||
- Monitor for failures
|
||||
- Aggregate coverage
|
||||
- Generate unified report
|
||||
|
||||
parallelization:
|
||||
- Group by file/module
|
||||
- Limit to CPU count
|
||||
- Kill all on fast-fail
|
||||
|
||||
```
|
||||
|
||||
Component: Command (automated with standard inputs)
|
||||
</example>
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
Over-orchestration:
|
||||
```yaml
|
||||
# BAD - no coordination needed
|
||||
coordination:
|
||||
- run git status
|
||||
- then run git diff
|
||||
- then run git log
|
||||
```
|
||||
|
||||
Tight coupling:
|
||||
|
||||
```yaml
|
||||
# BAD
|
||||
url: https://api.example.com/v1/users
|
||||
|
||||
# GOOD
|
||||
url: ${API_BASE_URL}/users
|
||||
```
|
||||
|
||||
Missing rollback:
|
||||
|
||||
```yaml
|
||||
# BAD
|
||||
steps:
|
||||
- deploy A
|
||||
- deploy B
|
||||
- deploy C
|
||||
|
||||
# GOOD
|
||||
steps:
|
||||
- deploy A
|
||||
- deploy B (rollback A on failure)
|
||||
- deploy C (rollback A+B on failure)
|
||||
```
|
||||
|
||||
### Hybrid Example
|
||||
|
||||
Adaptive CI pipeline combines orchestration + heuristics:
|
||||
|
||||
```yaml
|
||||
name: adaptive-ci-pipeline
|
||||
type: orchestration
|
||||
heuristic_aspects:
|
||||
- Skip expensive tests on draft PRs
|
||||
- Full suite on main
|
||||
- Parallel for large suites
|
||||
|
||||
coordination:
|
||||
Lint → Type Check → Unit → Integration → Deploy
|
||||
|
||||
decision_logic:
|
||||
- if: branch == main
|
||||
then: full suite + deploy
|
||||
- if: pr_status == draft
|
||||
then: lint + type check only
|
||||
- if: files_changed < 5
|
||||
then: affected tests only
|
||||
```
|
||||
|
||||
Component: Hook + Skill
|
||||
|
||||
---
|
||||
|
||||
## Heuristic Patterns
|
||||
|
||||
Decision rules and conditional logic.
|
||||
|
||||
### Examples
|
||||
|
||||
<example name="pr-size-heuristic">
|
||||
```yaml
|
||||
name: pr-size-heuristic
|
||||
type: heuristic
|
||||
description: Optimize PR size for review quality
|
||||
|
||||
condition: Calculate effective LOC
|
||||
action: Recommend splitting if over threshold
|
||||
rationale: Large PRs = slower review + lower quality feedback
|
||||
|
||||
thresholds:
|
||||
ideal: 100-250 LOC
|
||||
acceptable: 250-300 LOC
|
||||
warning: 300-500 LOC
|
||||
must_split: 500+ LOC
|
||||
|
||||
exceptions:
|
||||
- Mechanical changes (formatting, renames)
|
||||
- Lockfile updates
|
||||
- Batch refactoring with clear pattern
|
||||
|
||||
rules:
|
||||
- condition: LOC < 100
|
||||
action: Consider if PR is complete
|
||||
- condition: LOC 100-250
|
||||
action: Ideal, proceed
|
||||
- condition: LOC 300-500
|
||||
action: Strongly recommend splitting
|
||||
- condition: LOC > 500
|
||||
action: Must split unless mechanical
|
||||
|
||||
```
|
||||
|
||||
Component: Hook (pre-push check) + Skill (splitting guidance)
|
||||
</example>
|
||||
|
||||
<example name="technology-selection">
|
||||
```yaml
|
||||
name: technology-selection
|
||||
type: heuristic
|
||||
description: Framework for choosing tech/dependencies
|
||||
|
||||
criteria:
|
||||
maturity:
|
||||
- Stable API (v1.0+)
|
||||
- Active maintenance (3 months)
|
||||
- Production usage
|
||||
|
||||
ecosystem:
|
||||
- Documentation quality
|
||||
- Community size
|
||||
- Stack integration
|
||||
|
||||
technical:
|
||||
- Performance
|
||||
- Bundle size
|
||||
- Type safety
|
||||
|
||||
team:
|
||||
- Learning curve
|
||||
- Existing expertise
|
||||
|
||||
rules:
|
||||
- condition: problem has boring solution
|
||||
action: use established library
|
||||
- condition: library is critical path
|
||||
action: require high maturity
|
||||
- condition: library is peripheral
|
||||
action: optimize for simplicity
|
||||
|
||||
red_flags:
|
||||
- No updates in 12+ months
|
||||
- Security vulnerabilities
|
||||
- Frequent breaking changes
|
||||
```
|
||||
|
||||
Component: Skill (requires judgment)
|
||||
</example>
|
||||
|
||||
<example name="error-handling-strategy">
|
||||
```yaml
|
||||
name: error-handling-strategy
|
||||
type: heuristic
|
||||
description: Choose error handling by type/context
|
||||
|
||||
classifications:
|
||||
expected_recoverable:
|
||||
examples: [network timeout, file not found, validation]
|
||||
strategy: Return Result type, let caller decide
|
||||
|
||||
expected_unrecoverable:
|
||||
examples: [config error, db connection at startup]
|
||||
strategy: Fail fast with clear message
|
||||
|
||||
unexpected:
|
||||
examples: [null pointer, index out of bounds]
|
||||
strategy: Panic/throw, capture in boundary
|
||||
|
||||
degraded:
|
||||
examples: [cache miss, optional feature unavailable]
|
||||
strategy: Log warning, use fallback
|
||||
|
||||
recovery:
|
||||
retry: Transient errors, exponential backoff
|
||||
fallback: Optional enhancement unavailable
|
||||
compensate: Partial success, undo completed steps
|
||||
propagate: Caller has better context
|
||||
|
||||
```
|
||||
|
||||
Component: Skill (embedded guidance)
|
||||
</example>
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
Too rigid:
|
||||
```yaml
|
||||
# BAD
|
||||
condition: Function > 10 lines
|
||||
action: Must split
|
||||
# Ignores complexity, cohesion, readability
|
||||
```
|
||||
|
||||
Cargo cult:
|
||||
|
||||
```yaml
|
||||
# BAD
|
||||
condition: Writing React
|
||||
action: Must use hooks, never classes
|
||||
rationale: "Hooks are modern"
|
||||
```
|
||||
|
||||
Contradictory:
|
||||
|
||||
```yaml
|
||||
# BAD
|
||||
- condition: Code is complex
|
||||
action: Add comments
|
||||
- condition: Code needs comments
|
||||
action: Refactor to be clearer
|
||||
# When to comment vs refactor?
|
||||
```
|
||||
|
||||
### Hybrid Example
|
||||
|
||||
Adaptive testing combines heuristic + workflow:
|
||||
|
||||
```yaml
|
||||
name: adaptive-testing
|
||||
type: heuristic
|
||||
workflow_aspects:
|
||||
- Execute in optimal order
|
||||
- Report results
|
||||
|
||||
rules:
|
||||
- condition: changed files include tests
|
||||
action: run those first
|
||||
- condition: changes in /src/auth/
|
||||
action: run auth suite
|
||||
- condition: running locally
|
||||
action: affected tests only
|
||||
- condition: coverage < 80%
|
||||
action: warn, show uncovered
|
||||
|
||||
workflow:
|
||||
1. Analyze changed files
|
||||
2. Select test scope
|
||||
3. Execute in priority order
|
||||
4. Report with actionable feedback
|
||||
```
|
||||
|
||||
Component: Command + Skill
|
||||
|
||||
---
|
||||
|
||||
## Pattern Evolution
|
||||
|
||||
Patterns evolve as needs grow:
|
||||
|
||||
1. Manual Process → User runs tests, reads output, fixes
|
||||
2. Documented Workflow (Skill) → Structured steps
|
||||
3. Partial Automation (Skill + Command) → `/run-tests --watch`
|
||||
4. Event-Driven (Skill + Command + Hook) → Trigger on file save
|
||||
5. Intelligent Orchestration (Agent + Skills) → Decides what to run
|
||||
|
||||
Recognition triggers:
|
||||
- Manual → Workflow: User repeatedly asks "how do I..."
|
||||
- Workflow → Command: Fully automatable with known inputs
|
||||
- Command → Hook: Run at predictable times
|
||||
- Skill → Agent: Requires deep expertise
|
||||
- Single → Composite: Has automated + judgment aspects
|
||||
Reference in New Issue
Block a user