codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: requesting-code-review
+description: Use when preparing code for review before submitting PRs — covers pre-flight validation, change summary generation, test evidence collection, review focus areas, and structured review request formatting
+disable-model-invocation: true
+---
+
+# Requesting Code Review
+
+## Overview
+
+Prepare your code for review before asking others to look at it. A well-prepared review request gets faster, higher-quality feedback and respects the reviewer's time.
+
+**Core principle:** The author's job is to make the reviewer's job easy. Every minute you spend preparing saves ten minutes of back-and-forth.
+
+**Violating the letter of this process is violating the spirit of code review.**
+
+## When to Use
+
+**Always use for:**
+- New feature PRs
+- Bug fix PRs
+- Refactoring PRs
+- Any PR touching security-sensitive code
+- Any PR with breaking changes
+
+**Lighter preparation acceptable for:**
+- Documentation-only changes
+- Configuration tweaks
+- Single-line fixes with obvious intent
+
+**Never skip:**
+- Pre-Flight Checks (Phase 1) — takes 2 minutes, catches 80% of review round-trips
+
+## The Iron Law
+
+```
+NO REVIEW REQUEST WITHOUT PASSING TESTS AND SELF-REVIEW
+```
+
+If tests fail, fix them. If you haven't read your own diff, read it. Requesting review on broken or unreviewed code wastes everyone's time.
+
+## Quick Reference
+
+| Phase | Purpose | Time |
+|-------|---------|------|
+| 1. Pre-Flight Checks | Validate code is review-ready | ~2 min |
+| 2. Self-Review | Catch issues before the reviewer does | ~5-15 min |
+| 3. Change Summary | Explain what, why, and impact | ~5 min |
+| 4. Test Evidence | Prove it works | ~2 min |
+| 5. Review Focus Areas | Guide the reviewer's attention | ~3 min |
+| 6. Review Request Assembly | Format the PR description | ~5 min |
+
+## Phase 1: Pre-Flight Checks
+
+**Run before anything else. All must pass.**
+
+```bash
+# Tests passing
+npm test
+# Expected: all green, zero failures
+
+# TypeScript compilation
+npx tsc --noEmit
+# Expected: no errors
+
+# Linting
+npx eslint .
+# Expected: no errors (warnings acceptable)
+
+# Formatting
+npx prettier --check .
+# Expected: all files formatted
+```
+
+### Automated Check
+
+If the project has a validate script, use it:
+```bash
+npm run validate
+# Runs all checks in one command
+```
+
+### Diff Hygiene
+
+```bash
+# No TODO/FIXME in your changes
+git diff --cached | grep -n "TODO\|FIXME\|HACK\|XXX"
+# Expected: no matches (or documented exceptions)
+
+# No unintended files
+git diff --cached --name-only
+# Review: every file should be intentional
+
+# No debug artifacts
+git diff --cached | grep -n "console\.log\|debugger\|\.only("
+# Expected: no matches
+```
+
+**If ANY check fails → fix before proceeding. No exceptions.**
+
+## Phase 2: Self-Review
+
+**Read your own diff as if you are the reviewer.**
+
+```bash
+# View the full diff
+git diff main...HEAD
+# Or for staged changes:
+git diff --cached
+```
+
+### Self-Review Checklist
+
+```
+- [ ] Every changed file is intentional (no accidental modifications)
+- [ ] Variable and function names are clear without context
+- [ ] No hardcoded values that should be constants or config
+- [ ] Error cases handled (not just happy path)
+- [ ] Edge cases considered (null, empty, boundary values)
+- [ ] No copy-pasted code that should be extracted
+- [ ] Comments explain "why", not "what"
+- [ ] No leftover debugging code
+```
+
+### Common Issues to Catch
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Forgotten console.log | `grep -rn "console.log" src/` | Remove or replace with proper logging |
+| Hardcoded secrets | `grep -rn "password\|secret\|token\|apiKey" src/` | Move to environment variables |
+| Missing error handling | Look for unhandled promises, bare try/catch | Add specific error handling |
+| Overly large diff | `git diff --stat` shows 500+ lines | Split into smaller PRs |
+
+## Phase 3: Change Summary Generation
+
+**Answer three questions:**
+
+### 1. What Changed?
+
+```bash
+# File-level summary
+git diff main...HEAD --stat
+
+# Logical grouping of changes
+git log main..HEAD --oneline
+```
+
+Categorize changes:
+- **Added:** New files, functions, components, tests
+- **Modified:** Changed behavior, updated logic, fixed bugs
+- **Removed:** Deleted code, deprecated features
+- **Refactored:** Structural changes without behavior change
+
+### 2. Why Did It Change?
+
+Link to the motivation:
+- Issue/ticket reference (e.g., "Closes #123")
+- Problem statement (what was broken or missing)
+- Business context (why this matters now)
+
+### 3. What Could Break?
+
+```bash
+# Find direct dependents of changed files
+git diff main...HEAD --name-only | while read file; do
+  echo "=== $file ==="
+  grep -rn "from.*$(basename $file .ts)" src/ --include="*.ts" | head -5
+done
+```
+
+Assess impact radius:
+- **Direct:** Files importing your changed modules
+- **Indirect:** Consumers of your module's public API
+- **External:** API contracts, database schemas, config formats
+
+## Phase 4: Test Evidence
+
+**Show, don't tell. Include actual output.**
+
+### Test Results
+
+```bash
+# Run tests with verbose output
+npm test -- --reporter=verbose 2>&1 | tail -20
+
+# Example output to include:
+# ✓ should create user with valid email (3ms)
+# ✓ should reject duplicate email (2ms)
+# ✓ should handle network timeout (15ms)
+# Tests: 47 passed, 0 failed
+```
+
+### Coverage Delta
+
+```bash
+# Generate coverage report
+npm run test:coverage 2>&1 | grep -A 5 "Coverage summary"
+
+# Example output:
+# Statements   : 92.3% (+1.2%)
+# Branches     : 87.5% (+3.0%)
+# Functions    : 95.0% (+0.5%)
+# Lines        : 91.8% (+1.1%)
+```
+
+If coverage decreased, explain why:
+- Removed well-tested dead code
+- Added error handling paths not yet fully tested
+- New feature has planned follow-up test PR
+
+### New Tests Written
+
+List new test cases with descriptions:
+```
+New tests:
+- "should validate email format before creating user"
+- "should return 409 when email already exists"
+- "should retry on transient network failure"
+- "should timeout after 5 seconds"
+```
+
+## Phase 5: Review Focus Areas
+
+**Guide the reviewer to what matters most.**
+
+### Highlight Categories
+
+| Category | What to Flag | Example |
+|----------|-------------|---------|
+| **Complex logic** | Algorithms, state machines, tricky conditions | "The retry logic in `fetchWithBackoff` handles 5 failure modes" |
+| **Security-sensitive** | Auth, input validation, data exposure | "New endpoint requires auth — please verify middleware chain" |
+| **Breaking changes** | API changes, schema migrations, config changes | "Response format changed from array to paginated object" |
+| **Uncertainty** | Code you're not confident about | "Not sure if this caching strategy handles concurrent writes correctly" |
+| **Trade-offs** | Deliberate compromises | "Chose N+1 query for readability; volume is < 100 items" |
+
+### Format
+
+```markdown
+### Review Focus Areas
+
+1. **[Complex]** `src/services/retry.ts:25-60` — Exponential backoff
+   with jitter. Please verify the max delay calculation.
+
+2. **[Security]** `src/middleware/auth.ts:15` — Added rate limiting.
+   Check if the window size is appropriate.
+
+3. **[Breaking]** `src/api/users.ts:42` — Changed response from
+   `User[]` to `{ data: User[], pagination: Pagination }`.
+   All consumers need to update.
+
+4. **[Uncertain]** `src/cache/store.ts:78` — Cache invalidation
+   on concurrent writes. Would appreciate a second opinion.
+```
+
+## Phase 6: Review Request Assembly
+
+**Combine all phases into a structured PR description.**
+
+### PR Description Template
+
+```markdown
+## Summary
+
+[1-3 sentences: what this PR does and why]
+
+Closes #[issue-number]
+
+## Changes
+
+- [Categorized list from Phase 3]
+
+## Test Evidence
+
+- All tests passing: [X] passed, 0 failed
+- Coverage: [X]% (+/-Y%)
+- New tests: [count] added
+
+## Review Focus Areas
+
+1. **[Category]** `file:line` — [Description]
+2. **[Category]** `file:line` — [Description]
+
+## Impact
+
+- **Breaking changes:** [Yes/No — details if yes]
+- **Dependencies affected:** [list or "none"]
+- **Migration needed:** [Yes/No — steps if yes]
+
+## Checklist
+
+- [ ] Tests passing
+- [ ] Lint clean
+- [ ] No TODO/FIXME in diff
+- [ ] Self-reviewed
+- [ ] Documentation updated (if needed)
+```
+
+### PR Title Convention
+
+```
+<type>(<scope>): <description>
+
+Examples:
+  feat(auth): add JWT refresh token rotation
+  fix(api): handle timeout in user creation endpoint
+  refactor(db): extract query builder from repository
+```
+
+## Verification Checklist
+
+Before submitting the review request:
+
+```
+- [ ] All pre-flight checks passing (Phase 1)
+- [ ] Self-review completed, no issues found (Phase 2)
+- [ ] Change summary includes what, why, and impact (Phase 3)
+- [ ] Test evidence shows actual output, not "tests pass" (Phase 4)
+- [ ] At least one review focus area identified (Phase 5)
+- [ ] PR description follows template (Phase 6)
+- [ ] PR title follows convention
+- [ ] No TODO/FIXME in diff
+- [ ] No debug artifacts in diff
+- [ ] Branch is up-to-date with base
+```
+
+**Cannot check all boxes? Do not submit the review request.**
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "Tests are probably passing" | Run them. "Probably" is not evidence. |
+| "The diff is small, no need to self-review" | Small diffs cause big bugs. 2 minutes to check. |
+| "I'll add test evidence later" | Reviewers need it NOW to evaluate correctness. |
+| "The reviewer will figure out what changed" | That's YOUR job. Respect their time. |
+| "No breaking changes... I think" | Check consumers. "I think" is not analysis. |
+| "I'll just describe what I did" | Describe WHY, not just WHAT. |
+| "This is urgent, skip preparation" | Urgency increases risk. Preparation prevents rework. |
+| "The PR is too big to summarize" | Split it. If you can't summarize it, reviewers can't review it. |
+
+## Related Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `pr-review` | Complement — pr-review is for CONDUCTING reviews; this skill is for REQUESTING them |
+| `deployment-checklist` | Sequential — deploy after review approval |
+| `test-driven-development` | Supporting — TDD produces the test evidence this skill requires |
+| `security-audit` | Supporting — security audit informs review focus areas |

package/.ai-rules/skills/retrospective/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: retrospective
+description: "Analyze recent session context archives to identify coding patterns, agent usage, TDD cycle stats, and common EVAL issues. Generates a summary report with data-driven improvement suggestions."
+---
+
+# Session Retrospective
+
+## Overview
+
+Analyze accumulated PLAN/ACT/EVAL session data from context archives to surface coding habits, recurring patterns, and actionable improvement suggestions. Transforms passive session history into data-driven growth insights.
+
+**Core principle:** Decisions improve when informed by patterns, not just memory. Review what actually happened, not what you think happened.
+
+## When to Use
+
+- After completing a sprint or milestone
+- During periodic team/personal retrospectives
+- When noticing repeated issues across sessions
+- Before planning process improvements
+- When onboarding to understand team patterns
+
+## When NOT to Use
+
+- Mid-session (wait until a natural checkpoint)
+- With fewer than 3 archived sessions (insufficient data)
+- For real-time debugging (use `systematic-debugging` instead)
+
+## Prerequisites
+
+- Context archive system enabled (#999)
+- At least 3 archived sessions in `docs/codingbuddy/archive/`
+- MCP tools available: `get_context_history`, `search_context_archives`
+
+## Process
+
+### Phase 1: Data Collection
+
+Gather session archives and extract structured data.
+
+1. **Retrieve recent archives**
+   - Call `get_context_history` with appropriate limit (default: 20)
+   - If no archives exist, inform user and suggest running a few PLAN/ACT/EVAL sessions first
+   - Note the date range covered
+
+2. **Read archive contents**
+   - Read each archived context document
+   - Extract from each session:
+     - Mode transitions (PLAN, ACT, EVAL, AUTO)
+     - Primary agent used
+     - Task description and title
+     - Decisions made
+     - Notes recorded
+     - Progress items (ACT mode)
+     - Findings and recommendations (EVAL mode)
+     - Status (completed, in_progress, blocked)
+
+### Phase 2: Pattern Analysis
+
+Analyze collected data across five dimensions.
+
+#### 2a. Mode Usage Patterns
+
+- Count sessions per mode (PLAN, ACT, EVAL, AUTO)
+- Calculate EVAL adoption rate: `EVAL sessions / total sessions`
+- Identify sessions that skipped EVAL (potential quality gaps)
+- Flag AUTO mode usage frequency
+
+#### 2b. Agent Utilization
+
+- Rank agents by frequency of use
+- Identify underutilized specialists (available but rarely used)
+- Detect agent concentration (over-reliance on one agent)
+- Note any specialist gaps for the project's tech stack
+
+#### 2c. TDD Cycle Indicators
+
+Search archives for TDD-related patterns:
+- `search_context_archives` with keywords: "TDD", "test", "RED", "GREEN", "REFACTOR"
+- Count sessions mentioning test-first vs test-after
+- Identify sessions where tests were skipped or deferred
+- Calculate approximate TDD adherence rate
+
+#### 2d. Recurring Issues
+
+Search for repeated problems:
+- `search_context_archives` with keywords: "blocked", "failed", "error", "issue", "bug"
+- Group similar issues by category (build, test, integration, deployment)
+- Identify issues that appear in 2+ sessions (systemic problems)
+- Note resolution patterns (same fix applied repeatedly?)
+
+#### 2e. Decision Patterns
+
+Analyze decisions across sessions:
+- Extract all recorded decisions
+- Identify decisions that were later reversed or modified
+- Spot recurring decision themes (architecture, tooling, process)
+- Flag decisions made without EVAL validation
+
+### Phase 3: Report Generation
+
+Generate a structured markdown report.
+
+```markdown
+# Session Retrospective Report
+
+> Period: {start_date} - {end_date}
+> Sessions analyzed: {count}
+> Generated: {current_date}
+
+## Summary Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total sessions | {n} |
+| PLAN sessions | {n} |
+| ACT sessions | {n} |
+| EVAL sessions | {n} |
+| AUTO sessions | {n} |
+| EVAL adoption rate | {n}% |
+| Completion rate | {n}% |
+
+## Top Agents
+
+| Rank | Agent | Sessions | % |
+|------|-------|----------|---|
+| 1 | {agent} | {n} | {n}% |
+| ... | ... | ... | ... |
+
+## TDD Health
+
+- Adherence rate: {n}%
+- Test-first sessions: {n}
+- Test-after sessions: {n}
+- No-test sessions: {n}
+
+## Recurring Issues
+
+### {Issue Category}
+- **Frequency**: {n} sessions
+- **Pattern**: {description}
+- **Impact**: {assessment}
+
+## Key Decisions Timeline
+
+| Date | Decision | Mode | Validated? |
+|------|----------|------|------------|
+| {date} | {decision} | {mode} | {yes/no} |
+
+## Improvement Suggestions
+
+### High Priority
+1. {suggestion with rationale}
+
+### Medium Priority
+1. {suggestion with rationale}
+
+### Process Observations
+1. {observation}
+```
+
+### Phase 4: Improvement Suggestions
+
+Generate actionable suggestions based on findings.
+
+**Auto-generate suggestions for:**
+
+| Pattern Detected | Suggestion |
+|-----------------|------------|
+| EVAL rate < 30% | Increase EVAL usage for quality gates |
+| Single agent > 60% | Diversify specialist agents for broader coverage |
+| TDD adherence < 50% | Reinforce test-first discipline with TDD skill |
+| Same issue 3+ times | Create a checklist or rule to prevent recurrence |
+| Blocked sessions > 20% | Investigate common blockers and add preventive steps |
+| No decisions recorded | Improve decision documentation in context |
+| Decisions reversed > 2x | Add EVAL validation before major decisions |
+
+### Phase 5: Output
+
+1. **Display report** in conversation
+2. **Save report** to `docs/codingbuddy/retrospective-{YYYY-MM-DD}.md`
+3. **Offer next steps:**
+   - "Create GitHub issues for high-priority improvements?"
+   - "Update project rules based on findings?"
+   - "Schedule recurring retrospectives?"
+
+## Key Principles
+
+- **Data over opinion** - Base all observations on archive evidence
+- **Patterns over incidents** - Focus on recurring themes, not one-off events
+- **Actionable suggestions** - Every finding should have a clear next step
+- **No blame** - Focus on process improvement, not individual mistakes
+- **Incremental** - Suggest 2-3 improvements per retrospective, not a complete overhaul

package/.ai-rules/skills/rule-authoring/SKILL.md

@@ -271,3 +271,8 @@ NEVER / MUST NOT  → Prohibited
 | "The existing rule covers this" | Check carefully — overlap causes conflicts |
 | "Rules don't need testing" | Test with each target AI tool |
 | "Abstract rules are more flexible" | Abstract rules are ignored or misapplied |
+
+## Additional resources
+
+- [Rule template](examples/rule-template.md) — Copy-and-adapt template with filled example and pre-commit checklist
+- [Trigger patterns](examples/trigger-patterns.md) — Catalog of clear trigger patterns, ambiguity antipatterns, and strength vocabulary

package/.ai-rules/skills/rule-authoring/examples/rule-template.md

@@ -0,0 +1,142 @@
+# Rule Template
+
+Copy this template when writing new AI coding rules for `.ai-rules/rules/`.
+
+---
+
+## Rule File Template
+
+```markdown
+# <Category Name>
+
+<Brief description of what rules in this file govern and why they matter.>
+
+## Rules
+
+### <Rule Name>
+
+**When:** <Specific trigger condition — when does this rule activate?>
+
+**Do:** <Concrete action in imperative mood. One sentence.>
+
+**Don't:** <Specific anti-pattern to avoid. One sentence.>
+
+**Check:** <How to verify the rule was followed — must be testable.>
+
+**Example:**
+
+\`\`\`typescript
+// Good
+<correct code example>
+
+// Bad
+<incorrect code example>
+\`\`\`
+
+**Why:** <One-sentence rationale linking to a real consequence.>
+
+---
+
+### <Next Rule Name>
+
+...
+
+## Rationale
+
+<Why these rules exist for this project. Link to incidents, standards, or team decisions.>
+
+## Exceptions
+
+<Cases where these rules do not apply. Keep this list short — fewer exceptions = less ambiguity.>
+```
+
+---
+
+## Filled Example
+
+```markdown
+# TypeScript Strictness
+
+Rules for maintaining type safety across the codebase.
+
+## Rules
+
+### No `any` Type
+
+**When:** Writing or modifying TypeScript code.
+
+**Do:** Use explicit types for all function parameters and return values. Use `unknown` for truly unknown types, then narrow with type guards.
+
+**Don't:** Use `any` — it disables the compiler's ability to catch errors.
+
+**Check:** `npx tsc --noEmit` passes with `noImplicitAny: true` in tsconfig.json.
+
+**Example:**
+
+\`\`\`typescript
+// Good
+function parseInput(raw: unknown): ParsedData {
+  if (typeof raw !== 'string') throw new TypeError('Expected string');
+  return JSON.parse(raw) as ParsedData;
+}
+
+// Bad
+function parseInput(raw: any): any {
+  return JSON.parse(raw);
+}
+\`\`\`
+
+**Why:** `any` silently propagates through the type system and causes runtime errors that the compiler should have caught.
+
+---
+
+### Explicit Return Types on Exported Functions
+
+**When:** Defining a function that is exported from a module.
+
+**Do:** Annotate the return type explicitly.
+
+**Don't:** Rely on type inference for public API boundaries.
+
+**Check:** ESLint rule `@typescript-eslint/explicit-function-return-type` on exported functions.
+
+**Example:**
+
+\`\`\`typescript
+// Good
+export function calculateTotal(items: LineItem[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// Bad
+export function calculateTotal(items: LineItem[]) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+\`\`\`
+
+**Why:** Explicit return types act as documentation and prevent accidental API changes when internal implementation changes.
+
+## Rationale
+
+TypeScript strict mode catches ~40% of bugs at compile time. These rules ensure we get the full benefit of the type system.
+
+## Exceptions
+
+- Test files (`.test.ts`, `.spec.ts`) may use `as` casting for test fixtures.
+- Third-party library type augmentation files may require `any` in `.d.ts` declarations.
+```
+
+---
+
+## Checklist Before Committing a New Rule
+
+```
+- [ ] "When" trigger is specific (not "always" or "when appropriate")
+- [ ] "Do" action is imperative and unambiguous
+- [ ] "Don't" anti-pattern is concrete
+- [ ] "Check" criterion is automatable or clearly verifiable
+- [ ] Example shows both correct and incorrect code
+- [ ] "Why" links to a real consequence (not "best practice")
+- [ ] Rule doesn't duplicate an existing rule
+- [ ] Rule works with all target AI tools (Claude, Cursor, Copilot, Q, Kiro)
+```