📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -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% |
|
||||
Reference in New Issue
Block a user