diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e53405cfc..4d77d6d37 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,9 +1,9 @@ { - "name": "superpowers-dev", - "description": "Development marketplace for Superpowers core skills library", + "name": "jthurlburt-claude-plugins", + "description": "Custom plugins for Claude Code", "owner": { - "name": "Jesse Vincent", - "email": "jesse@fsck.com" + "name": "Jacob Hurlburt", + "email": "[email protected]" }, "plugins": [ { @@ -12,9 +12,9 @@ "version": "3.2.2", "source": "./", "author": { - "name": "Jesse Vincent", - "email": "jesse@fsck.com" - } + "name": "Jacob Hurlburt" + }, + "strict": true } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 43d3e9de6..d3e8c08a1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -9,5 +9,12 @@ "homepage": "https://github.com/obra/superpowers", "repository": "https://github.com/obra/superpowers", "license": "MIT", - "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"] + "keywords": [ + "skills", + "tdd", + "debugging", + "collaboration", + "best-practices", + "workflows" + ] } diff --git a/.gitignore b/.gitignore index 848a68435..f88aad2d1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .worktrees/ .private-journal/ +/node_modules/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..c59ced720 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,42 @@ +repos: + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v4.0.0-alpha.8 + hooks: + - id: prettier + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-merge-conflict + args: [--assume-in-merge] + - id: check-yaml + args: [--unsafe] + - id: no-commit-to-branch + args: [--branch, main] + - id: debug-statements + - id: mixed-line-ending + - repo: https://github.com/gitleaks/gitleaks + rev: v8.18.4 + hooks: + - id: gitleaks + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.11.9 + hooks: + - id: ruff + args: [--fix] + - id: ruff-format + - repo: https://github.com/adamchainz/blacken-docs + rev: 1.19.1 + hooks: + - id: blacken-docs + additional_dependencies: + - black==22.12.0 + - repo: https://github.com/ikamensh/flynt + rev: 1.0.6 + hooks: + - id: flynt + - repo: https://github.com/rhysd/actionlint + rev: v1.7.7 + hooks: + - id: actionlint diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..43e5bf445 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,96 @@ +# Changelog + +## Fork Information + +**Forked from**: [obra/superpowers](https://github.com/obra/superpowers) v3.2.2 +**Marketplace**: `jthurlburt/claude-settings` + +This is a personal fork with additional skills and enhancements borrowed from multiple sources. + +## [Unreleased] + +### Added + +- Knowledge management integration: Opt-in [ADR](https://adr.github.io/) (Architecture Decision Records) and DISCOVERIES patterns from [Microsoft Amplifier](https://github.com/microsoft/amplifier) (2025-11-03) + - `/setup-knowledge-management` slash command with embedded templates + - 9 skills updated to integrate with `docs/decisions/` and `docs/discoveries/` when present + - Skills fall back to `mem` for personal tracking when patterns not enabled + - Comprehensive integration documented in `docs/decisions/001-adopt-knowledge-management.md` + +## Attribution + +Skills and concepts borrowed from: + +- [obra/superpowers](https://github.com/obra/superpowers) - Base framework and core skills +- [superpowers-skills](https://github.com/obra/superpowers-skills) - Problem-solving patterns +- [CCPlugins](https://github.com/brennercruvinel/CCPlugins) - Development workflow skills +- [claude-codex-settings](https://github.com/fcakyon/claude-codex-settings/tree/main) - Enhancement concepts and hooks +- [Microsoft Amplifier](https://github.com/microsoft/amplifier) - Ambiguity and tension management patterns + +## Added Skills + +**From superpowers-skills:** + +- `simplification-cascades` - Find unifying principles that eliminate components +- `collision-zone-thinking` - Force unrelated concepts together for innovation +- `meta-pattern-recognition` - Spot universal patterns across domains +- `inversion-exercise` - Flip assumptions to reveal alternatives +- `scale-game` - Test at extremes to expose fundamental truths +- `when-stuck` - Dispatch router to appropriate problem-solving technique +- `tracing-knowledge-lineages` - Understand technical decision evolution +- `preserving-productive-tensions` - Recognize when to preserve multiple approaches + +**From CCPlugins:** + +- `documentation-management` - Holistic documentation maintenance +- `predict-issues` - Proactive problem identification with risk assessment +- `code-and-project-cleanup` - Safe cleanup of code and project artifacts + +**New skills:** + +- `extracting-patterns-from-projects` - Systematic analysis methodology for external projects (2025-10-23) +- `enhancing-superpowers` - Project-specific integration guide for superpowers (2025-10-23) + +## Enhanced Skills + +Skills with added capabilities from concept extraction: + +**brainstorming:** + +- External source adaptation pattern +- Progressive reasoning framework (steel man alternatives, bias checking) + +**systematic-debugging:** + +- Auto-fix patterns with skill linkage for common test failures + +**predict-issues:** + +- Security-specific risk analysis (exploitability, exposure, blast radius) + +**executing-plans:** + +- Continuous validation between tasks (type checks, import validation) + +**finishing-a-development-branch:** + +- Documentation synchronization check +- Optional commit history cleanup guidance + +**writing-plans:** + +- Existing pattern survey before planning + +**receiving-code-review:** + +- Pattern alignment checks before implementing feedback + +**dispatching-parallel-agents:** + +- Generalized from debugging-only to cover research, analysis, and any parallel tasks (2025-10-23) + +## Structural Changes + +- Flattened skills directory structure (removed nested categories) +- Standardized skill names to Title Case per Anthropic guidelines +- Added hooks from claude-codex-settings for session management diff --git a/README.md b/README.md index 5bbbb929a..a0e324b16 100644 --- a/README.md +++ b/README.md @@ -6,18 +6,30 @@ Give Claude Code superpowers with a comprehensive skills library of proven techn - **Testing Skills** - TDD, async testing, anti-patterns - **Debugging Skills** - Systematic debugging, root cause tracing, verification +- **Problem-Solving Skills** - Simplification, innovation, pattern recognition, assumption challenges +- **Research Skills** - Decision archaeology, knowledge lineage tracing - **Collaboration Skills** - Brainstorming, planning, code review, parallel agents -- **Development Skills** - Git worktrees, finishing branches, subagent workflows +- **Development Skills** - Git worktrees, finishing branches, subagent workflows, cleanup automation +- **Documentation Skills** - Holistic documentation management - **Meta Skills** - Creating, testing, and sharing skills Plus: -- **Slash Commands** - `/superpowers:brainstorm`, `/superpowers:write-plan`, `/superpowers:execute-plan` + +- **Slash Commands** - `/superpowers:brainstorm`, `/superpowers:write-plan`, `/superpowers:execute-plan`, `/superpowers:setup-knowledge-management` +- **Knowledge Management** - Opt-in [ADR](https://adr.github.io/) (Architecture Decision Records) and DISCOVERIES patterns for tracking decisions and non-obvious solutions - **Automatic Integration** - Skills activate automatically when relevant - **Consistent Workflows** - Systematic approaches to common engineering tasks -## Learn More +## Attribution + +This is a personal fork of [obra/superpowers](https://github.com/obra/superpowers) with additional skills and enhancements borrowed from: + +- [superpowers-skills](https://github.com/obra/superpowers-skills) - Problem-solving patterns +- [CCPlugins](https://github.com/brennercruvinel/CCPlugins) - Development workflow skills +- [claude-codex-settings](https://github.com/fcakyon/claude-codex-settings/tree/main) - Enhancement concepts +- [Microsoft Amplifier](https://github.com/microsoft/amplifier) - Tension management patterns -Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/) +See [CHANGELOG.md](CHANGELOG.md) for detailed changes and additions. ## Installation @@ -25,8 +37,8 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/ ```bash # In Claude Code -/plugin marketplace add obra/superpowers-marketplace -/plugin install superpowers@superpowers-marketplace +/plugin marketplace add jthurlburt/claude-settings +/plugin install superpowers@jthurlburt-claude-plugins ``` ### Verify Installation @@ -46,16 +58,19 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/ ### Using Slash Commands **Brainstorm a design:** + ``` /superpowers:brainstorm ``` **Create an implementation plan:** + ``` /superpowers:write-plan ``` **Execute the plan:** + ``` /superpowers:execute-plan ``` @@ -63,6 +78,7 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/ ### Automatic Skill Activation Skills activate automatically when relevant. For example: + - `test-driven-development` activates when implementing features - `systematic-debugging` activates when debugging issues - `verification-before-completion` activates before claiming work is done @@ -71,33 +87,59 @@ Skills activate automatically when relevant. For example: ### Skills Library -**Testing** (`skills/testing/`) +**Testing** + - **test-driven-development** - RED-GREEN-REFACTOR cycle - **condition-based-waiting** - Async test patterns - **testing-anti-patterns** - Common pitfalls to avoid +- **testing-skills-with-subagents** - Validate skill quality -**Debugging** (`skills/debugging/`) -- **systematic-debugging** - 4-phase root cause process +**Debugging** + +- **systematic-debugging** - 4-phase root cause process (enhanced) - **root-cause-tracing** - Find the real problem - **verification-before-completion** - Ensure it's actually fixed - **defense-in-depth** - Multiple validation layers -**Collaboration** (`skills/collaboration/`) -- **brainstorming** - Socratic design refinement -- **writing-plans** - Detailed implementation plans -- **executing-plans** - Batch execution with checkpoints +**Problem-Solving** + +- **simplification-cascades** - Find unifying principles that eliminate components +- **collision-zone-thinking** - Force unrelated concepts together for innovation +- **meta-pattern-recognition** - Spot universal patterns across domains +- **inversion-exercise** - Flip assumptions to reveal alternatives +- **scale-game** - Test at extremes to expose fundamental truths +- **when-stuck** - Dispatch router to appropriate problem-solving technique +- **predict-issues** - Proactive problem identification with risk assessment (enhanced) + +**Research & Architecture** + +- **tracing-knowledge-lineages** - Understand technical decision evolution +- **preserving-productive-tensions** - Recognize when to preserve multiple approaches +- **extracting-patterns-from-projects** - Systematic analysis methodology for external projects + +**Collaboration** + +- **brainstorming** - Socratic design refinement (enhanced) +- **writing-plans** - Detailed implementation plans (enhanced) +- **executing-plans** - Batch execution with checkpoints (enhanced) - **dispatching-parallel-agents** - Concurrent subagent workflows - **requesting-code-review** - Pre-review checklist -- **receiving-code-review** - Responding to feedback -- **using-git-worktrees** - Parallel development branches -- **finishing-a-development-branch** - Merge/PR decision workflow +- **receiving-code-review** - Responding to feedback (enhanced) - **subagent-driven-development** - Fast iteration with quality gates -**Meta** (`skills/meta/`) +**Development Workflow** + +- **using-git-worktrees** - Parallel development branches +- **finishing-a-development-branch** - Merge/PR decision workflow (enhanced) +- **documentation-management** - Holistic documentation maintenance +- **code-and-project-cleanup** - Safe cleanup of code and project artifacts + +**Meta** + - **writing-skills** - Create new skills following best practices - **sharing-skills** - Contribute skills back via branch and PR -- **testing-skills-with-subagents** - Validate skill quality - **using-superpowers** - Introduction to the skills system +- **enhancing-superpowers** - Project-specific integration guide for superpowers ### Commands @@ -132,14 +174,14 @@ Skills live directly in this repository. To contribute: 4. Use the `testing-skills-with-subagents` skill to validate quality 5. Submit a PR -See `skills/meta/writing-skills/SKILL.md` for the complete guide. +See `skills/writing-skills/SKILL.md` for the complete guide. ## Updating Skills update automatically when you update the plugin: ```bash -/plugin update superpowers +/plugin update superpowers@jthurlburt/claude-settings ``` ## License diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md deleted file mode 100644 index e9cb98b17..000000000 --- a/RELEASE-NOTES.md +++ /dev/null @@ -1,385 +0,0 @@ -# Superpowers Release Notes - -## v3.2.2 (2025-10-21) - -### Improvements - -**Strengthened using-superpowers skill against agent rationalization** -- Added EXTREMELY-IMPORTANT block with absolute language about mandatory skill checking - - "If even 1% chance a skill applies, you MUST read it" - - "You do not have a choice. You cannot rationalize your way out." -- Added MANDATORY FIRST RESPONSE PROTOCOL checklist - - 5-step process agents must complete before any response - - Explicit "responding without this = failure" consequence -- Added Common Rationalizations section with 8 specific evasion patterns - - "This is just a simple question" → WRONG - - "I can check files quickly" → WRONG - - "Let me gather information first" → WRONG - - Plus 5 more common patterns observed in agent behavior - -These changes address observed agent behavior where they rationalize around skill usage despite clear instructions. The forceful language and pre-emptive counter-arguments aim to make non-compliance harder. - -### Files Changed -- Updated: `skills/using-superpowers/SKILL.md` - Added three layers of enforcement to prevent skill-skipping rationalization - -## v3.2.1 (2025-10-20) - -### New Features - -**Code reviewer agent now included in plugin** -- Added `superpowers:code-reviewer` agent to plugin's `agents/` directory -- Agent provides systematic code review against plans and coding standards -- Previously required users to have personal agent configuration -- All skill references updated to use namespaced `superpowers:code-reviewer` -- Fixes #55 - -### Files Changed -- New: `agents/code-reviewer.md` - Agent definition with review checklist and output format -- Updated: `skills/requesting-code-review/SKILL.md` - References to `superpowers:code-reviewer` -- Updated: `skills/subagent-driven-development/SKILL.md` - References to `superpowers:code-reviewer` - -## v3.2.0 (2025-10-18) - -### New Features - -**Design documentation in brainstorming workflow** -- Added Phase 4: Design Documentation to brainstorming skill -- Design documents now written to `docs/plans/YYYY-MM-DD--design.md` before implementation -- Restores functionality from original brainstorming command that was lost during skill conversion -- Documents written before worktree setup and implementation planning -- Tested with subagent to verify compliance under time pressure - -### Breaking Changes - -**Skill reference namespace standardization** -- All internal skill references now use `superpowers:` namespace prefix -- Updated format: `superpowers:test-driven-development` (previously just `test-driven-development`) -- Affects all REQUIRED SUB-SKILL, RECOMMENDED SUB-SKILL, and REQUIRED BACKGROUND references -- Aligns with how skills are invoked using the Skill tool -- Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills - -### Improvements - -**Design vs implementation plan naming** -- Design documents use `-design.md` suffix to prevent filename collisions -- Implementation plans continue using existing `YYYY-MM-DD-.md` format -- Both stored in `docs/plans/` directory with clear naming distinction - -## v3.1.1 (2025-10-17) - -### Bug Fixes - -- **Fixed command syntax in README** (#44) - Updated all command references to use correct namespaced syntax (`/superpowers:brainstorm` instead of `/brainstorm`). Plugin-provided commands are automatically namespaced by Claude Code to avoid conflicts between plugins. - -## v3.1.0 (2025-10-17) - -### Breaking Changes - -**Skill names standardized to lowercase** -- All skill frontmatter `name:` fields now use lowercase kebab-case matching directory names -- Examples: `brainstorming`, `test-driven-development`, `using-git-worktrees` -- All skill announcements and cross-references updated to lowercase format -- This ensures consistent naming across directory names, frontmatter, and documentation - -### New Features - -**Enhanced brainstorming skill** -- Added Quick Reference table showing phases, activities, and tool usage -- Added copyable workflow checklist for tracking progress -- Added decision flowchart for when to revisit earlier phases -- Added comprehensive AskUserQuestion tool guidance with concrete examples -- Added "Question Patterns" section explaining when to use structured vs open-ended questions -- Restructured Key Principles as scannable table - -**Anthropic best practices integration** -- Added `skills/writing-skills/anthropic-best-practices.md` - Official Anthropic skill authoring guide -- Referenced in writing-skills SKILL.md for comprehensive guidance -- Provides patterns for progressive disclosure, workflows, and evaluation - -### Improvements - -**Skill cross-reference clarity** -- All skill references now use explicit requirement markers: - - `**REQUIRED BACKGROUND:**` - Prerequisites you must understand - - `**REQUIRED SUB-SKILL:**` - Skills that must be used in workflow - - `**Complementary skills:**` - Optional but helpful related skills -- Removed old path format (`skills/collaboration/X` → just `X`) -- Updated Integration sections with categorized relationships (Required vs Complementary) -- Updated cross-reference documentation with best practices - -**Alignment with Anthropic best practices** -- Fixed description grammar and voice (fully third-person) -- Added Quick Reference tables for scanning -- Added workflow checklists Claude can copy and track -- Appropriate use of flowcharts for non-obvious decision points -- Improved scannable table formats -- All skills well under 500-line recommendation - -### Bug Fixes - -- **Re-added missing command redirects** - Restored `commands/brainstorm.md` and `commands/write-plan.md` that were accidentally removed in v3.0 migration -- Fixed `defense-in-depth` name mismatch (was `Defense-in-Depth-Validation`) -- Fixed `receiving-code-review` name mismatch (was `Code-Review-Reception`) -- Fixed `commands/brainstorm.md` reference to correct skill name -- Removed references to non-existent related skills - -### Documentation - -**writing-skills improvements** -- Updated cross-referencing guidance with explicit requirement markers -- Added reference to Anthropic's official best practices -- Improved examples showing proper skill reference format - -## v3.0.1 (2025-10-16) - -### Changes - -We now use Anthropic's first-party skills system! - -## v2.0.2 (2025-10-12) - -### Bug Fixes - -- **Fixed false warning when local skills repo is ahead of upstream** - The initialization script was incorrectly warning "New skills available from upstream" when the local repository had commits ahead of upstream. The logic now correctly distinguishes between three git states: local behind (should update), local ahead (no warning), and diverged (should warn). - -## v2.0.1 (2025-10-12) - -### Bug Fixes - -- **Fixed session-start hook execution in plugin context** (#8, PR #9) - The hook was failing silently with "Plugin hook error" preventing skills context from loading. Fixed by: - - Using `${BASH_SOURCE[0]:-$0}` fallback when BASH_SOURCE is unbound in Claude Code's execution context - - Adding `|| true` to handle empty grep results gracefully when filtering status flags - ---- - -# Superpowers v2.0.0 Release Notes - -## Overview - -Superpowers v2.0 makes skills more accessible, maintainable, and community-driven through a major architectural shift. - -The headline change is **skills repository separation**: all skills, scripts, and documentation have moved from the plugin into a dedicated repository ([obra/superpowers-skills](https://github.com/obra/superpowers-skills)). This transforms superpowers from a monolithic plugin into a lightweight shim that manages a local clone of the skills repository. Skills auto-update on session start. Users fork and contribute improvements via standard git workflows. The skills library versions independently from the plugin. - -Beyond infrastructure, this release adds nine new skills focused on problem-solving, research, and architecture. We rewrote the core **using-skills** documentation with imperative tone and clearer structure, making it easier for Claude to understand when and how to use skills. **find-skills** now outputs paths you can paste directly into the Read tool, eliminating friction in the skills discovery workflow. - -Users experience seamless operation: the plugin handles cloning, forking, and updating automatically. Contributors find the new architecture makes improving and sharing skills trivial. This release lays the foundation for skills to evolve rapidly as a community resource. - -## Breaking Changes - -### Skills Repository Separation - -**The biggest change:** Skills no longer live in the plugin. They've been moved to a separate repository at [obra/superpowers-skills](https://github.com/obra/superpowers-skills). - -**What this means for you:** - -- **First install:** Plugin automatically clones skills to `~/.config/superpowers/skills/` -- **Forking:** During setup, you'll be offered the option to fork the skills repo (if `gh` is installed) -- **Updates:** Skills auto-update on session start (fast-forward when possible) -- **Contributing:** Work on branches, commit locally, submit PRs to upstream -- **No more shadowing:** Old two-tier system (personal/core) replaced with single-repo branch workflow - -**Migration:** - -If you have an existing installation: -1. Your old `~/.config/superpowers/.git` will be backed up to `~/.config/superpowers/.git.bak` -2. Old skills will be backed up to `~/.config/superpowers/skills.bak` -3. Fresh clone of obra/superpowers-skills will be created at `~/.config/superpowers/skills/` - -### Removed Features - -- **Personal superpowers overlay system** - Replaced with git branch workflow -- **setup-personal-superpowers hook** - Replaced by initialize-skills.sh - -## New Features - -### Skills Repository Infrastructure - -**Automatic Clone & Setup** (`lib/initialize-skills.sh`) -- Clones obra/superpowers-skills on first run -- Offers fork creation if GitHub CLI is installed -- Sets up upstream/origin remotes correctly -- Handles migration from old installation - -**Auto-Update** -- Fetches from tracking remote on every session start -- Auto-merges with fast-forward when possible -- Notifies when manual sync needed (branch diverged) -- Uses pulling-updates-from-skills-repository skill for manual sync - -### New Skills - -**Problem-Solving Skills** (`skills/problem-solving/`) -- **collision-zone-thinking** - Force unrelated concepts together for emergent insights -- **inversion-exercise** - Flip assumptions to reveal hidden constraints -- **meta-pattern-recognition** - Spot universal principles across domains -- **scale-game** - Test at extremes to expose fundamental truths -- **simplification-cascades** - Find insights that eliminate multiple components -- **when-stuck** - Dispatch to right problem-solving technique - -**Research Skills** (`skills/research/`) -- **tracing-knowledge-lineages** - Understand how ideas evolved over time - -**Architecture Skills** (`skills/architecture/`) -- **preserving-productive-tensions** - Keep multiple valid approaches instead of forcing premature resolution - -### Skills Improvements - -**using-skills (formerly getting-started)** -- Renamed from getting-started to using-skills -- Complete rewrite with imperative tone (v4.0.0) -- Front-loaded critical rules -- Added "Why" explanations for all workflows -- Always includes /SKILL.md suffix in references -- Clearer distinction between rigid rules and flexible patterns - -**writing-skills** -- Cross-referencing guidance moved from using-skills -- Added token efficiency section (word count targets) -- Improved CSO (Claude Search Optimization) guidance - -**sharing-skills** -- Updated for new branch-and-PR workflow (v2.0.0) -- Removed personal/core split references - -**pulling-updates-from-skills-repository** (new) -- Complete workflow for syncing with upstream -- Replaces old "updating-skills" skill - -### Tools Improvements - -**find-skills** -- Now outputs full paths with /SKILL.md suffix -- Makes paths directly usable with Read tool -- Updated help text - -**skill-run** -- Moved from scripts/ to skills/using-skills/ -- Improved documentation - -### Plugin Infrastructure - -**Session Start Hook** -- Now loads from skills repository location -- Shows full skills list at session start -- Prints skills location info -- Shows update status (updated successfully / behind upstream) -- Moved "skills behind" warning to end of output - -**Environment Variables** -- `SUPERPOWERS_SKILLS_ROOT` set to `~/.config/superpowers/skills` -- Used consistently throughout all paths - -## Bug Fixes - -- Fixed duplicate upstream remote addition when forking -- Fixed find-skills double "skills/" prefix in output -- Removed obsolete setup-personal-superpowers call from session-start -- Fixed path references throughout hooks and commands - -## Documentation - -### README -- Updated for new skills repository architecture -- Prominent link to superpowers-skills repo -- Updated auto-update description -- Fixed skill names and references -- Updated Meta skills list - -### Testing Documentation -- Added comprehensive testing checklist (`docs/TESTING-CHECKLIST.md`) -- Created local marketplace config for testing -- Documented manual testing scenarios - -## Technical Details - -### File Changes - -**Added:** -- `lib/initialize-skills.sh` - Skills repo initialization and auto-update -- `docs/TESTING-CHECKLIST.md` - Manual testing scenarios -- `.claude-plugin/marketplace.json` - Local testing config - -**Removed:** -- `skills/` directory (82 files) - Now in obra/superpowers-skills -- `scripts/` directory - Now in obra/superpowers-skills/skills/using-skills/ -- `hooks/setup-personal-superpowers.sh` - Obsolete - -**Modified:** -- `hooks/session-start.sh` - Use skills from ~/.config/superpowers/skills -- `commands/brainstorm.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT -- `commands/write-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT -- `commands/execute-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT -- `README.md` - Complete rewrite for new architecture - -### Commit History - -This release includes: -- 20+ commits for skills repository separation -- PR #1: Amplifier-inspired problem-solving and research skills -- PR #2: Personal superpowers overlay system (later replaced) -- Multiple skill refinements and documentation improvements - -## Upgrade Instructions - -### Fresh Install - -```bash -# In Claude Code -/plugin marketplace add obra/superpowers-marketplace -/plugin install superpowers@superpowers-marketplace -``` - -The plugin handles everything automatically. - -### Upgrading from v1.x - -1. **Backup your personal skills** (if you have any): - ```bash - cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup - ``` - -2. **Update the plugin:** - ```bash - /plugin update superpowers - ``` - -3. **On next session start:** - - Old installation will be backed up automatically - - Fresh skills repo will be cloned - - If you have GitHub CLI, you'll be offered the option to fork - -4. **Migrate personal skills** (if you had any): - - Create a branch in your local skills repo - - Copy your personal skills from backup - - Commit and push to your fork - - Consider contributing back via PR - -## What's Next - -### For Users - -- Explore the new problem-solving skills -- Try the branch-based workflow for skill improvements -- Contribute skills back to the community - -### For Contributors - -- Skills repository is now at https://github.com/obra/superpowers-skills -- Fork → Branch → PR workflow -- See skills/meta/writing-skills/SKILL.md for TDD approach to documentation - -## Known Issues - -None at this time. - -## Credits - -- Problem-solving skills inspired by Amplifier patterns -- Community contributions and feedback -- Extensive testing and iteration on skill effectiveness - ---- - -**Full Changelog:** https://github.com/obra/superpowers/compare/dd013f6...main -**Skills Repository:** https://github.com/obra/superpowers-skills -**Issues:** https://github.com/obra/superpowers/issues diff --git a/commands/setup-knowledge-management.md b/commands/setup-knowledge-management.md new file mode 100644 index 000000000..4cfd71afe --- /dev/null +++ b/commands/setup-knowledge-management.md @@ -0,0 +1,294 @@ +# Setup Knowledge Management + +Set up ADR (Architecture Decision Records) and DISCOVERIES pattern for this project. + +## Overview + +This command creates an opt-in knowledge management structure: +- `docs/decisions/` for Architecture Decision Records +- `docs/discoveries/` for tracking non-obvious problems and solutions + +These complement personal `mem` usage with project-level, git-tracked documentation. + +## Pre-flight Checks + +BEFORE creating anything, check: + +1. Does `docs/decisions/` exist? +2. Does `docs/discoveries/` exist? +3. Does `docs/decisions/README.md` exist? +4. Does `docs/discoveries/DISCOVERIES.md` exist? + +Commands: +```bash +ls -la docs/decisions/ 2>/dev/null +ls -la docs/discoveries/ 2>/dev/null +test -f docs/decisions/README.md && echo "README exists" +test -f docs/discoveries/DISCOVERIES.md && echo "DISCOVERIES exists" +``` + +## Decision Logic + +### If ALL checks are clean (nothing exists): +Proceed with "Setup Steps" below. + +### If ANY already exist: +**STOP immediately.** + +Report what exists: +```bash +echo "Found existing structure:" +test -d docs/decisions && echo " - docs/decisions/" +test -d docs/discoveries && echo " - docs/discoveries/" +test -f docs/decisions/README.md && echo " - docs/decisions/README.md" +test -f docs/discoveries/DISCOVERIES.md && echo " - docs/discoveries/DISCOVERIES.md" +``` + +Present options to user: +1. **Skip setup** - Keep existing structure, don't modify +2. **Create only missing pieces** - Add what's missing, preserve what exists +3. **Show templates** - Display what would be created for manual review + +Wait for user to choose before proceeding. + +## Setup Steps + +Only execute if pre-flight checks are clean. + +### Step 1: Create directory structure + +```bash +mkdir -p docs/decisions +mkdir -p docs/discoveries +``` + +### Step 2: Create docs/decisions/README.md + +Create file with this exact content: + +```markdown +# Architecture Decision Records (ADRs) + +This directory tracks significant architectural and design decisions for the project. + +## When to Create an ADR + +Create a decision record when: +- Making architectural choices (patterns, frameworks, approaches) +- Choosing between multiple valid approaches +- Making decisions that will be hard to reverse +- Establishing project conventions or standards +- Making trade-offs that future developers should understand + +**Use `mem` for quick decision tracking in solo work.** + +**Use ADRs when:** +- Decisions affect team members +- Complex decisions requiring full justification +- Decisions you want in git history +- Formal documentation is valuable + +## ADR Template + +Copy this template for new decisions: + +\`\`\`markdown +# [DECISION-NNN] Title + +**Status**: Active | Deprecated | Superseded +**Date**: YYYY-MM-DD + +## Context +Why was this decision needed? What problem are we solving? + +## Decision +What did we decide to do? + +## Rationale +Why this approach over alternatives? + +## Alternatives Considered +What other options did we evaluate? +- **Option A**: Description and why rejected +- **Option B**: Description and why rejected + +## Consequences + +**Positive:** +- ✅ Benefit 1 +- ✅ Benefit 2 + +**Negative/Risks:** +- ⚠️ Trade-off 1 +- ⚠️ Trade-off 2 + +## Review Triggers +When should we reconsider this decision? +- [ ] Condition 1 +- [ ] Condition 2 +\`\`\` + +## Naming Convention + +Files: `NNN-short-description.md` where NNN is zero-padded number (001, 002, etc.) + +Examples: +- `001-use-typescript-for-frontend.md` +- `002-adopt-microservices-architecture.md` + +## Updating Status + +When revisiting decisions: +- **Deprecated**: No longer recommended, but still in use +- **Superseded**: Replaced by another decision (link to it) + +## Tips + +- Write ADRs when fresh - capture context while it's clear +- Include specific examples and code snippets +- Link to relevant issues, PRs, or documentation +- Update status when circumstances change +- One decision per ADR (don't bundle) +``` + +### Step 3: Create docs/discoveries/DISCOVERIES.md + +Create file with this exact content: + +```markdown +# Discoveries + +This document tracks non-obvious problems, their root causes, solutions, and prevention strategies. Check here before debugging similar issues. + +**Use `mem` for personal discovery tracking in solo work.** + +**Use this file when:** +- Project-specific issues that affect team members +- Problems you want in git history +- Issues requiring structured documentation +- Collective learning is valuable + +## Template + +Copy this template for new entries: + +\`\`\`markdown +## Issue Title (YYYY-MM-DD) + +### Issue +Clear description of the problem observed. Include symptoms and error messages. + +### Root Cause +What actually caused it? Not just symptoms - trace to the source. + +### Solution +How was it fixed? Specific steps, code changes, or configuration updates. + +### Prevention +How to avoid this in the future? Patterns, checks, validation, or practices to adopt. +\`\`\` + +--- + +## Discoveries + +*No discoveries yet. This section will grow as we encounter and solve non-obvious problems.* + + +``` + +### Step 4: Verify structure created + +Run verification commands: + +```bash +echo "Verifying structure..." +ls -la docs/decisions/ +ls -la docs/discoveries/ +echo "" +echo "Verifying file contents..." +wc -l docs/decisions/README.md +wc -l docs/discoveries/DISCOVERIES.md +``` + +Expected output: +- Both directories exist +- README.md has ~80+ lines +- DISCOVERIES.md has ~40+ lines + +### Step 5: Optional - Create example ADR + +Ask user: "Would you like to create an example ADR (001-adopt-knowledge-management.md) documenting this decision to adopt these patterns?" + +If yes, create `docs/decisions/001-adopt-knowledge-management.md`: + +```markdown +# [DECISION-001] Adopt Knowledge Management Patterns + +**Status**: Active +**Date**: YYYY-MM-DD + +## Context + +Working solo and in teams, we need to track architectural decisions and non-obvious problem solutions. The `mem` system works well for personal knowledge but doesn't provide: +- Team visibility (others can't see decisions/discoveries) +- Git history (no tracking of when/why decisions changed) +- Discoverability (team members don't know what's been solved) + +## Decision + +Adopt opt-in knowledge management patterns: +- Architecture Decision Records (ADRs) in `docs/decisions/` +- DISCOVERIES pattern in `docs/discoveries/DISCOVERIES.md` + +These complement `mem` (personal) with project-level (team) documentation. + +## Rationale + +- **Opt-in**: Only enable in projects where valuable, no forcing on teams +- **Complements mem**: Use mem for solo work, files for team sharing +- **Git-tracked**: Decisions and discoveries preserved in version control +- **Discoverable**: Team members can browse `docs/` to learn project context + +Follows patterns from Microsoft Amplifier project, adapted for our needs. + +## Alternatives Considered + +- **Just use mem**: Rejected - doesn't share with team, not in git +- **Force in all projects**: Rejected - violates autonomy, creates empty dirs everywhere +- **Separate skill**: Rejected - better to integrate into existing workflows + +## Consequences + +**Positive:** +- ✅ Project-level knowledge preserved +- ✅ Team members can discover decisions/solutions +- ✅ Git history tracks evolution of thinking +- ✅ Skills automatically use when present + +**Negative/Risks:** +- ⚠️ Another system to maintain (but opt-in mitigates) +- ⚠️ Need discipline to document (but skills prompt) +- ⚠️ Template versioning (embedded in slash command) + +## Review Triggers +- [ ] If team adoption is low after 3 months +- [ ] If maintenance burden becomes significant +- [ ] If mem system evolves to cover team use cases +``` + +### Step 6: Stage and commit + +```bash +git add docs/ +git commit -m "docs: add knowledge management structure (ADR + DISCOVERIES)" +``` + +## Completion + +Structure created successfully. Skills will automatically detect and use these patterns when present. + +**Next steps:** +- Document architectural decisions as they're made +- Add discoveries when solving non-obvious problems +- Share with team members diff --git a/docs/amplifier-analysis.md b/docs/amplifier-analysis.md new file mode 100644 index 000000000..ace184d53 --- /dev/null +++ b/docs/amplifier-analysis.md @@ -0,0 +1,1199 @@ +# Amplifier Project Analysis: Transferable Concepts for Superpowers + +**Date**: 2025-10-23 (Updated: 2025-11-02) +**Analyst**: Claude (Sonnet 4.5) +**Purpose**: Identify patterns, features, and concepts from Microsoft's Amplifier project that could enhance the Superpowers skills library + +--- + +## 🆕 Update (2025-11-02) + +### Changes in Amplifier Since Initial Analysis + +**Major Addition: Design Intelligence Capability (Oct 26, 2025)** 🎨 + +Amplifier added a comprehensive design capability with: +- **7 new design specialist agents** (animation-choreographer, art-director, component-designer, design-system-architect, layout-architect, responsive-strategist, voice-strategist) +- **4 design philosophy documents** in ai_context/ (DESIGN-PHILOSOPHY.md, DESIGN-PRINCIPLES.md, DESIGN-FRAMEWORK.md, DESIGN-VISION.md) +- **Design knowledge base** (5 files): color theory, animation principles, accessibility, typography +- **Design protocols** (5 files): component creation, design checklist, anti-patterns, wireframe standards +- **/designer orchestration command** for coordinating design work + +**Total agent count**: Now **30 agents** (up from 23 in original analysis) + +**Other Notable Changes:** +- **Git commit attribution guidelines** added to AGENTS.md - all commits now include Amplifier footer +- **"Respect User Time" principle** added to AGENTS.md - emphasizes testing before presenting +- **DevContainer improvements** - better cache handling and shell configuration +- **DISCOVERIES.md updates** - new entries for pnpm setup issues + +### Changes in Claude-Settings Since Initial Analysis + +The superpowers project has evolved: +- **Codex integration** - experimental support for shared skill repositories +- **Enhanced documentation-management** skill - now requires inline source links +- **Improved PR creation** - enhanced to analyze full branch history +- **Writing clarity improvements** applied across multiple skills +- **Brainstorming skill** merged with upstream proactive research patterns + +### Impact on Original Recommendations + +**✅ Recommendations Still Valid:** +- All Tier 1 recommendations (DISCOVERIES.md, decision tracking, philosophy docs) remain highly relevant +- PreCompact transcript system still critical +- Lightweight DDD patterns extraction approach unchanged +- Defensive programming utilities still valuable + +**📊 New Considerations:** + +1. **Design Capability Assessment Needed** + - The design intelligence capability is domain-specific (UI/UX design) + - **Not recommended for superpowers** unless working on design-heavy projects + - Pattern worth noting: Multi-agent orchestration via /designer command + - Could inspire similar orchestration patterns for other domains + +2. **Commit Attribution Pattern** + - Amplifier now mandates attribution footer in all commits + - **Aligns with existing guidance** in base.md (no AI attribution) + - Superpowers should maintain stance: clean git history without AI attribution + +3. **"Respect User Time" Principle** + - Excellent addition to AGENTS.md emphasizing thorough testing before presenting + - **Already implicit in superpowers** via verification-before-completion skill + - Could make this principle more explicit in using-superpowers or base documentation + +4. **Agent Count Growth** + - Amplifier now at 30 agents (7 new design specialists) + - Reinforces original conclusion: **Extract patterns, don't port agents** + - Skills-based approach remains superior for automatic activation + +### Updated Priority Assessment + +**Tier 1 (Unchanged):** 4-6 hours +- DISCOVERIES.md Pattern ✅ +- Decision Tracking System ✅ +- Philosophy Documentation ✅ + +**Tier 2 (Unchanged):** 8-12 hours +- PreCompact Transcript System ✅ +- Lightweight DDD Patterns ✅ +- Enhanced SessionStart Hook ✅ + +**Tier 3 (Minor Update):** 15-20 hours +- Defensive Programming Utilities ✅ +- New Skills from Agent Patterns ✅ +- Enhanced Status Line ✅ +- Additional Hooks ✅ +- **NEW: Consider multi-domain orchestration pattern** (inspired by /designer) - 2-3 hours if needed + +**Not Recommended:** +- ❌ Design Intelligence capability (too domain-specific) +- ❌ Mandatory commit attribution (conflicts with clean history principle) + +### Conclusion + +The original analysis remains **highly accurate**. Amplifier's design capability addition demonstrates the project's continued evolution but doesn't change the core integration strategy: **extract proven patterns and infrastructure, maintain skills-based philosophy, avoid architectural porting**. + +The addition of 7 design-specific agents (23→30 total) reinforces that agent proliferation is a natural outcome of the explicit-invocation model, while superpowers' auto-activation approach should remain focused on broadly applicable workflows. + +--- + +## Executive Summary + +After extensive review of the [Amplifier project](https://github.com/microsoft/amplifier), I've identified **18+ transferable patterns** organized into 5 categories. The most valuable additions focus on **knowledge management**, **workflow infrastructure**, and **defensive programming patterns** that would enhance all existing skills without requiring major architectural changes. + +**Key Finding**: Rather than porting Amplifier's agent-based architecture, extract proven **patterns and principles** that align with Superpowers' lightweight, skills-based philosophy. + +**Estimated Impact**: +- 30% reduction in repeated problem-solving (knowledge management) +- Better decision continuity across sessions (decision tracking) +- Higher reliability in LLM integrations (defensive patterns) +- Never lose context to compaction (transcript system) +- Clearer feature development workflows (document-first patterns) + +--- + +## Project Comparison + +### Amplifier vs Superpowers: Philosophical Alignment + +Both projects share core values but take different architectural approaches: + +| Aspect | Amplifier | Superpowers | Alignment | +|--------|-----------|-------------|-----------| +| **Philosophy** | Ruthless Simplicity, Modular Design | Test-first, Systematic workflows, Simplicity | ✅ Strong | +| **Architecture** | 23 specialized agents | 33 skills with auto-activation | Different but complementary | +| **Activation** | Explicit invocation | Automatic when relevant | Superpowers approach is lighter | +| **Workflow** | Document-Driven Development (5 phases) | Plan → Execute with skills | Can be merged | +| **Knowledge** | DISCOVERIES.md, decision tracking | Skills as knowledge | Amplifier adds persistence | +| **Infrastructure** | Rich hooks, transcript system | SessionStart hook, basic setup | Amplifier is more mature | + +**Key Insight**: Amplifier demonstrates a **production-tested, mature ecosystem** around Claude Code. Superpowers provides **elegant, automatic skill activation**. The best path is extracting Amplifier's infrastructure and knowledge patterns while maintaining Superpowers' skills-based approach. + +--- + +## Category 1: Knowledge Management Systems + +### 1.1 DISCOVERIES.md Pattern + +**What It Is**: +- Living document tracking non-obvious problems, root causes, solutions +- Structured format: Date, Issue, Root Cause, Solution, Prevention +- Regular review/cleanup to remove outdated entries +- Integration with development workflow + +**Example Entry**: +```markdown +## OneDrive/Cloud Sync File I/O Errors (2025-01-21) + +### Issue +Knowledge synthesis experiencing intermittent I/O errors (OSError errno 5) +in WSL2 environment. + +### Root Cause +Directory symlinked to OneDrive folder. "Cloud-only" files cause failures +while OneDrive fetches them. + +### Solution +1. Added retry logic with exponential backoff +2. Created centralized file I/O utility module +3. Warning message suggests "Always keep on this device" + +### Prevention +- Enable "Always keep on device" for development folders +- Use centralized file_io utility for all operations +- Test with cloud sync scenarios +``` + +**Value for Superpowers**: +- **Prevents repeated debugging**: Check DISCOVERIES before investigating similar issues +- **Builds institutional memory**: Preserve solutions across sessions +- **Complements existing skills**: Enhances `systematic-debugging`, `when-stuck` + +**Implementation Effort**: Low (1 hour) +- Create DISCOVERIES.md template +- Update 2-3 skills to reference it +- Add to SessionStart reminder + +**Trade-offs**: +- ✅ Minimal effort, high value +- ✅ Works with existing workflow +- ⚠️ Requires discipline to maintain (but so do skills) + +--- + +### 1.2 Decision Tracking System (ADR Pattern) + +**What It Is**: +Architecture Decision Records in structured format: +- Context: Why this decision was needed +- Decision: What was decided +- Rationale: Why this over alternatives +- Alternatives Considered: What was rejected and why +- Consequences: Positive, negative, risks +- Review Triggers: When to reconsider + +**Example from Amplifier**: +```markdown +# [DECISION-001] Use Skills Over Plugin System + +**Status**: Active +**Date**: 2025-09-15 + +## Context +Need extensible system for adding capabilities. Two options: +marketplace plugins or skills system. + +## Decision +Use Claude Code's first-party skills system rather than plugins. + +## Rationale +- Skills activate automatically when relevant +- No explicit user invocation needed +- Better integration with Claude's context +- Simpler distribution model + +## Alternatives Considered +- Plugin marketplace: More complex, requires explicit activation +- Mixed approach: Unnecessary complexity + +## Consequences +- ✅ Seamless user experience +- ✅ Automatic skill discovery +- ⚠️ Tied to Claude Code's skills implementation + +## Review Triggers +- [ ] If Claude Code deprecates skills system +- [ ] If user feedback requests plugin flexibility +``` + +**Value for Superpowers**: +- **Context preservation**: AI assistants remember why decisions were made +- **Prevents reversals**: Can't unknowingly undo well-reasoned choices +- **Learning system**: Patterns emerge showing what works/doesn't + +**Implementation Effort**: Low-Medium (2-3 hours) +- Create decisions/ directory with README template +- Document 3-5 key existing decisions retroactively +- Create new skill: `architectural-decision-making` + +**Trade-offs**: +- ✅ Extremely valuable for long-term projects +- ✅ Prevents costly mistakes +- ⚠️ Requires initial effort to document existing decisions +- ⚠️ Another system to maintain (but self-documenting) + +--- + +### 1.3 ai_working/ Directory Structure + +**What It Is**: +Organized workspace for AI artifacts: +``` +ai_working/ +├── decisions/ # Decision records +├── ddd/ # Document-driven development artifacts +│ ├── plan.md +│ ├── code_plan.md +│ └── impl_status.md +├── analysis/ # Research and analysis +└── README.md # Directory purpose +``` + +**Value for Superpowers**: +- **Organized artifacts**: Plans, analysis, temp work all in one place +- **Gitignored by default**: Don't pollute project history +- **Persistent across sessions**: AI can resume work + +**Implementation Effort**: Very Low (30 minutes) +- Already have `.claude/` for some things +- Create `ai_working/` with README +- Update `.gitignore` + +**Trade-offs**: +- ✅ Minimal effort +- ✅ Clean organization +- ⚠️ Users might not adopt without clear examples + +--- + +## Category 2: Workflow Infrastructure + +### 2.1 Document-Driven Development (DDD) Pattern + +**What It Is**: +5-phase workflow where documentation leads and code follows: + +1. **Plan** (`/ddd:1-plan`) - Design feature, create plan.md +2. **Docs** (`/ddd:2-docs`) - Update ALL non-code files first +3. **Code Plan** (`/ddd:3-code-plan`) - Plan implementation from docs +4. **Code** (`/ddd:4-code`) - Implement and test until working +5. **Finish** (`/ddd:5-finish`) - Cleanup and finalize + +**Key Principles**: +- Documentation IS the specification +- Docs updated BEFORE code +- Approval gates at phase transitions +- Artifacts from each phase feed the next +- Prevents doc drift (impossible to lag behind code) + +**Value for Superpowers**: +- **Prevents context poisoning**: Single source of truth +- **Cheaper iterations**: Fix design before implementation +- **Clear contracts**: Interfaces defined before complexity +- **AI-optimized**: Clear specs, no ambiguity + +**Implementation Effort**: High (8-10 hours for full workflow) +- Port 5 slash commands +- Create workflow state management +- Update multiple skills to reference DDD +- Write comprehensive documentation + +**Trade-offs**: +- ✅ Extremely powerful for complex features +- ✅ Prevents expensive mistakes +- ⚠️ Heavyweight - may be overkill for simple tasks +- ⚠️ Requires user buy-in to follow workflow +- 💡 **Alternative**: Extract lighter patterns (see 2.2) + +--- + +### 2.2 Lightweight DDD Patterns (Extraction Approach) + +Rather than port full DDD workflow, extract proven patterns: + +**Pattern 1: Artifact-Driven Phases** +- Each phase creates artifacts (plan.md, code_plan.md, etc.) +- Next phase consumes previous artifacts +- Can resume work across sessions + +**Pattern 2: Approval Gates** +- Human reviews at critical transitions +- Explicit user confirmation before proceeding +- Prevents expensive mistakes + +**Pattern 3: Retcon Writing** +- Write docs "as if feature already exists" +- More natural, easier to validate +- Reduces hedging language + +**Pattern 4: Documentation-First Mindset** +- Always update docs before code +- Docs are specification, not afterthought +- Prevents drift by design + +**Value for Superpowers**: +- Get DDD benefits without heavyweight workflow +- Integrate patterns into existing skills +- Works with current planning/execution approach + +**Implementation Effort**: Medium (4-5 hours) +- Create new skill: `document-first-development` +- Enhance existing `writing-plans` with artifact creation +- Enhance `executing-plans` with approval gates +- Add retcon writing to `documentation-management` + +**Trade-offs**: +- ✅ Gets core benefits without complexity +- ✅ Fits existing workflow better +- ✅ Users can adopt incrementally +- ⚠️ Less structured than full DDD + +**Recommendation**: Use lightweight extraction approach rather than full DDD port. + +--- + +### 2.3 Enhanced Hooks Ecosystem + +Amplifier has 7 sophisticated hooks: + +**Hook 1: PreCompact Transcript Export** ⭐ +- Automatically exports full conversation before compaction +- Saves to `.data/transcripts/` with timestamp +- Never lose context again +- Paired with `/transcripts` command to restore + +**Hook 2: SessionStart Enhancements** +- Load project-specific context (AGENTS.md, philosophy docs) +- Show project status and recent activity +- Display available tools/commands +- Set up environment + +**Hook 3: Stop/SubagentStop Session Cleanup** +- Save session statistics +- Export final state +- Cleanup temp files +- Memory persistence + +**Hook 4: SubagentLogger** +- Track subagent invocations +- Log prompts and results +- Analyze usage patterns +- Optimize delegation + +**Hook 5: PostToolUse Code Change Detection** +- Detect Edit/Write tool usage +- Auto-format on save (optional) +- Run quick validation +- Update documentation index + +**Hook 6: PostToolUse General Tracking** +- Tool usage analytics +- Performance monitoring +- Error tracking +- Cost attribution + +**Hook 7: Notification Handler** +- Process system notifications +- Update status displays +- Log important events + +**Value for Superpowers**: +- **Transcript system**: Highest value - never lose context +- **SessionStart**: Better project setup +- **Analytics**: Understand usage patterns + +**Implementation Effort**: Medium-High (5-7 hours for all) +- PreCompact + /transcripts: 3 hours (highest priority) +- SessionStart enhancements: 2 hours +- Analytics hooks: 2 hours (optional) + +**Trade-offs**: +- ✅ PreCompact is extremely high value +- ✅ Works with all existing skills +- ⚠️ Python dependencies (but minimal) +- ⚠️ Need to maintain hook scripts + +**Recommendation**: Implement PreCompact transcript system first, consider others later. + +--- + +### 2.4 Enhanced Status Line + +**What It Is**: +Rich status display showing real-time information: +``` +~/repos/amplifier (main → origin) Opus 4.1 💰$4.67 ⏱18m +``` + +Components: +- Current directory +- Git branch and tracking status +- Model name with cost-tier coloring (red=high, yellow=mid, blue=low) +- Running session cost +- Session duration + +**Value for Superpowers**: +- **Cost awareness**: See spending in real-time +- **Context awareness**: Know where you are +- **Session tracking**: Time management + +**Implementation Effort**: Medium (2-3 hours) +- Port statusline script +- Add cost tracking logic +- Create `/statusline` setup command +- Documentation + +**Trade-offs**: +- ✅ Nice quality-of-life improvement +- ✅ Pure infrastructure (no skill changes) +- ⚠️ Requires shell script maintenance +- ⚠️ May need platform-specific versions + +--- + +## Category 3: Philosophy & Documentation + +### 3.1 IMPLEMENTATION_PHILOSOPHY.md + +**What It Contains**: + +**Section 1: Core Philosophy** +- Ruthless Simplicity (KISS principle to extreme) +- Architectural Integrity with Minimal Implementation +- Library Usage Philosophy (use as intended, minimal wrappers) + +**Section 2: Technical Guidelines** +- API Layer: minimal endpoints, focused validation +- Database: simple schema, defer normalization +- MCP Implementation: streamlined, essential only +- Event System: simple pub/sub +- LLM Integration: direct, minimal transformation + +**Section 3: Development Approach** +- Vertical Slices: complete end-to-end features first +- Iterative Implementation: 80/20 principle +- Testing Strategy: emphasis on integration/e2e +- Error Handling: common cases robust, fail fast in dev + +**Section 4: Problem Analysis Before Implementation** ⭐ +Key pattern: "Analyze First, Don't Code" +1. Break down problem before implementing +2. Structured analysis with options and trade-offs +3. Recommendation with justification +4. Implementation plan + +**Section 5: Decision-Making Framework** +Questions to ask: +1. Do we need this right now? +2. What's the simplest way? +3. Can we solve this more directly? +4. Does complexity add proportional value? +5. How easy to understand/change later? + +**Section 6: Areas to Embrace vs Simplify** +- Embrace complexity: Security, data integrity, core UX, error visibility +- Aggressively simplify: Internal abstractions, future-proofing, edge cases, framework usage + +**Value for Superpowers**: +- **Consistent decision-making**: Framework for all choices +- **Philosophy alignment**: Already matches Superpowers values +- **Reference for all skills**: "Check philosophy before proceeding" + +**Implementation Effort**: Low (1-2 hours) +- Port document to docs/ +- Adapt examples for Superpowers context +- Reference from key skills +- Add to SessionStart context + +**Trade-offs**: +- ✅ Extremely high value for consistency +- ✅ Already aligns with Superpowers +- ✅ Minimal effort to add +- ⚠️ Another doc to maintain (but stable) + +--- + +### 3.2 MODULAR_DESIGN_PHILOSOPHY.md + +**What It Contains**: + +**Core Concept: "Bricks and Studs"** +Think of software modules like LEGO bricks: +- **Brick** = self-contained directory with one clear responsibility +- **Stud** = public contract (interfaces) other bricks connect to +- Regenerate whole bricks rather than line-edit +- Modules under 150 lines (AI-regeneratable in one shot) + +**7 Key Principles**: +1. **Think "bricks & studs"** - Self-contained modules with clear interfaces +2. **Start with contract** - Define inputs/outputs/dependencies first +3. **Build in isolation** - No internal imports from other modules +4. **Verify with lightweight tests** - Contract-level behavior tests +5. **Regenerate, don't patch** - Rewrite whole module from spec +6. **Parallel variants allowed** - Try multiple approaches simultaneously +7. **Human ↔️ AI handshake** - Human architects/QA, AI builds + +**Value for Superpowers**: +- **Clear module design**: Skills are already module-like +- **Regeneration mindset**: AI rewrites skills when needed +- **Testing philosophy**: Complements existing test skills +- **Parallel exploration**: Supports experimentation + +**Implementation Effort**: Low (1 hour) +- Port document +- Adapt examples +- Reference from `writing-skills`, `modular-builder` concepts + +**Trade-offs**: +- ✅ Excellent philosophical alignment +- ✅ Validates existing Superpowers approach +- ✅ Provides language for discussing design +- ⚠️ Might need examples updated for skills context + +--- + +### 3.3 Zero-BS Principle & Response Authenticity + +**Zero-BS Principle**: +No unnecessary stubs, placeholders, or future code: +- Never `raise NotImplementedError` (except abstract base classes) +- Never `TODO` comments without accompanying code +- Never `pass` as placeholder +- Never "Coming soon" features +- Build working code or don't build it + +**Response Authenticity Guidelines**: +Professional communication without sycophancy: +- Never: "You're absolutely right!", "Brilliant idea!", "Excellent point!" +- Instead: Analyze merit, discuss trade-offs, disagree constructively +- Focus on code/problems, not praising the person + +**Value for Superpowers**: +- **Code quality**: Enforce working code only +- **Communication**: Professional, honest feedback +- **Already aligned**: Matches Superpowers values + +**Implementation Effort**: Very Low (30 minutes) +- Add to philosophy docs +- Add reminder to SessionStart +- Reference from relevant skills + +**Trade-offs**: +- ✅ Easy to add +- ✅ Immediate impact on quality +- ✅ No maintenance burden + +--- + +## Category 4: Defensive Programming Patterns + +### 4.1 CCSDK Toolkit Defensive Utilities + +Amplifier includes battle-tested utilities in `amplifier/ccsdk_toolkit/defensive/`: + +**Utility 1: parse_llm_json()** ⭐ +Extracts JSON from any LLM response format: +- Markdown code blocks (```json ... ```) +- Mixed prose with embedded JSON +- Explanatory text before/after JSON +- Nested JSON structures +- Malformed quotes + +```python +# Instead of: +result = json.loads(llm_response) # ❌ Fails on wrapped JSON + +# Use: +result = parse_llm_json(llm_response, default={}) # ✅ Always works +``` + +**Utility 2: retry_with_feedback()** +Intelligent retry with error correction: +- Retries with error details sent to LLM +- LLM can self-correct based on what went wrong +- Exponential backoff +- Configurable max retries + +**Utility 3: isolate_prompt()** +Prevents context contamination: +- Adds clear delimiters around user content +- Prevents system instructions from bleeding into content +- Protects against prompt injection + +**Utility 4: write_json_with_retry() / read_json_with_retry()** +Cloud sync-aware file operations: +- Handles OneDrive/Dropbox/iCloud delays +- Retries with exponential backoff +- Informative warnings about cloud sync +- Works in WSL2 with Windows file systems + +**Utility 5: Incremental Processing Pattern** +Save after every item, not at end: +- Fixed filenames that overwrite (not timestamps) +- Users can abort without losing work +- Resume from where left off +- Enable selective retry + +**Real-World Validation**: +From DISCOVERIES.md: md_synthesizer tool showed: +- ✅ Zero JSON parsing errors (was 100% failure before) +- ✅ Zero context contamination +- ✅ Zero crashes +- ✅ 62.5% completion rate vs 0% before + +**Value for Superpowers**: +- **Reliability**: All LLM interactions more robust +- **Proven patterns**: Battle-tested in production +- **Universal application**: Benefits all skills using LLMs + +**Implementation Effort**: Medium (3-4 hours) +- Create `tools/defensive_patterns/` Python module +- Port 5 key utilities (no SDK dependency needed) +- Create new skill: `defensive-llm-integration` +- Add examples and docs +- Reference from `subagent-driven-development`, `dispatching-parallel-agents` + +**Trade-offs**: +- ✅ High reliability gains +- ✅ Lightweight Python utilities +- ✅ No Claude SDK dependency needed +- ⚠️ Python code to maintain +- ⚠️ Need to promote usage in skills + +**Recommendation**: High value for projects using subagents or custom tools. May be overkill if only using skills. + +--- + +## Category 5: Agent Patterns (Extract, Don't Port) + +### 5.1 Amplifier's 23 Agents + +Amplifier includes specialized agents in `.claude/agents/`: + +**Development Agents**: +- zen-architect (design, planning, review) +- modular-builder (implementation) +- bug-hunter (debugging) +- test-coverage (testing) +- refactor-architect (refactoring) +- integration-specialist (integration) +- performance-optimizer (optimization) + +**Knowledge Agents**: +- concept-extractor +- insight-synthesizer +- knowledge-archaeologist +- visualization-architect + +**Analysis Agents**: +- analysis-expert +- synthesis-master +- triage-specialist + +**Meta Agents**: +- subagent-architect (creates new agents) +- ambiguity-guardian (clarifies requirements) +- pattern-emergence (identifies patterns) + +### 5.2 Agents vs Skills Analysis + +**Key Differences**: + +| Aspect | Amplifier Agents | Superpowers Skills | +|--------|------------------|-------------------| +| Invocation | Explicit user command | Automatic activation | +| Context | Separate session with specific prompt | Integrated into main session | +| Scope | Focused, specialized task | Broader, workflow-oriented | +| Weight | Heavier (full agent invocation) | Lighter (skill guidance) | +| Discovery | Must know agent exists | Auto-discovered when relevant | +| Learning Curve | Steeper (which agent for what?) | Gentler (skills just work) | + +**Superpowers Advantages**: +- ✅ Automatic activation (no need to remember to use) +- ✅ Integrated workflows (skills work together) +- ✅ Easier for users (less cognitive load) +- ✅ Better for common tasks + +**Amplifier Advantages**: +- ✅ Focused expertise (deep specialization) +- ✅ Clean context (no main session pollution) +- ✅ Parallel execution (multiple agents at once) +- ✅ Better for complex analysis tasks + +### 5.3 Extraction Strategy: Patterns, Not Ports + +Rather than port 23 agents, **extract their patterns** into skills: + +**Pattern 1: Analysis-First (from zen-architect)** +Before implementing, always: +1. "Let me analyze this problem first" +2. Break down into components +3. Present 2-3 approaches with trade-offs +4. Recommend with justification +5. Create implementation plan + +**Pattern 2: Proactive Usage Triggers (from multiple agents)** +Define clear triggers for when skills should activate: +- "When user requests feature" → activate test-driven-development +- "When user reports bug" → activate systematic-debugging +- "When implementing module" → reference modular-design philosophy + +**Pattern 3: Operating Modes (from zen-architect)** +Skills can have conditional behavior: +- ANALYZE mode for new features +- ARCHITECT mode for system design +- REVIEW mode for code quality + +**Pattern 4: Specialized Guidance (from ambiguity-guardian)** +Active clarification patterns: +- Detect ambiguous requirements +- Ask specific clarifying questions +- Refuse to proceed without clarity +- Document assumptions explicitly + +**Pattern 5: Pattern Recognition (from pattern-emergence)** +Meta-skill for identifying patterns: +- Spot repeated structures +- Extract reusable components +- Suggest generalization +- Identify anti-patterns + +### 5.4 Recommended New Skills (Extracted from Agents) + +Based on agent analysis, these new skills would fill gaps: + +**Skill 1: modular-construction** (from modular-builder, zen-architect) +- Bricks & studs implementation guidance +- Contract-first design +- Module size guidelines (<150 lines) +- Regeneration over patching mindset +- Integration testing focus + +**Skill 2: requirement-clarification** (from ambiguity-guardian) +- Detect ambiguous requirements +- Active clarification process +- Assumption documentation +- Approval before proceeding +- Reduces rework from misunderstanding + +**Skill 3: contract-first-design** (from zen-architect, api-contract-designer) +- Interface before implementation +- Define inputs/outputs/side-effects +- Create testable contracts +- Enable parallel development +- Support regeneration + +**Skill 4: knowledge-management** (new, from decision tracking + DISCOVERIES) +- When to create/consult DISCOVERIES entries +- When to create/consult decision records +- How to maintain knowledge systems +- Integration with other skills + +**Skill 5: document-first-development** (from DDD, lighter version) +- Always update docs before code +- Retcon writing technique +- Artifact creation patterns +- Approval gates +- Documentation-code sync + +**Implementation Effort**: Medium-High (8-12 hours for all 5) +- Each skill: 1.5-2.5 hours +- Testing and documentation +- Integration with existing skills + +**Trade-offs**: +- ✅ Fills real gaps in Superpowers +- ✅ Extracts best patterns from agents +- ✅ Maintains skills-based philosophy +- ⚠️ Increases total skill count (33 → 38) +- ⚠️ Need to ensure good auto-activation + +--- + +## Recommendations by Priority + +### 🔥 Tier 1: Implement First (Highest Value, Lowest Effort) + +**Estimated Total: 4-6 hours** + +1. **DISCOVERIES.md Pattern** (1 hour) + - Create template + - Integrate with `systematic-debugging` and `when-stuck` + - Add to SessionStart reminder + - **Why**: Prevents repeated problem-solving, builds institutional knowledge + +2. **Decision Tracking System** (2-3 hours) + - Create decisions/ with README template + - Document 3-5 key existing decisions + - Create `architectural-decision-making` skill + - **Why**: Preserves context across sessions, prevents uninformed reversals + +3. **Philosophy Documentation** (1-2 hours) + - Port IMPLEMENTATION_PHILOSOPHY.md + - Port MODULAR_DESIGN_PHILOSOPHY.md + - Add Zero-BS and Response Authenticity sections + - Reference from key skills + - **Why**: Provides decision-making framework, aligns with existing values + +**Impact**: Immediate improvement in consistency, knowledge preservation, decision quality + +--- + +### ⚡ Tier 2: Implement Next (High Value, Moderate Effort) + +**Estimated Total: 8-12 hours** + +4. **PreCompact Transcript System** (3-4 hours) + - Port hook_precompact.py + - Create .data/transcripts/ structure + - Add /transcripts restoration command + - **Why**: Never lose context to compaction, enables long-running sessions + +5. **Lightweight DDD Patterns** (4-5 hours) + - Create `document-first-development` skill + - Enhance `writing-plans` with artifact creation + - Enhance `executing-plans` with approval gates + - Add retcon writing to `documentation-management` + - **Why**: Gets DDD benefits without heavyweight workflow complexity + +6. **Enhanced SessionStart Hook** (1-2 hours) + - Load philosophy docs + - Show project status + - Display available commands/skills + - **Why**: Better project setup, more context for every session + +**Impact**: Major workflow improvements, never lose work, better planning + +--- + +### 🎯 Tier 3: Consider Later (Good Value, Higher Effort or Specialized) + +**Estimated Total: 15-20 hours** + +7. **Defensive Programming Utilities** (3-4 hours) + - Create tools/defensive_patterns/ module + - Port 5 key utilities + - Create `defensive-llm-integration` skill + - **Why**: Higher reliability for custom tool/subagent development + - **Note**: May be overkill if primarily using skills + +8. **New Skills from Agent Patterns** (8-12 hours) + - `modular-construction` (2 hours) + - `requirement-clarification` (2 hours) + - `contract-first-design` (2 hours) + - `knowledge-management` (2 hours) + - `document-first-development` (already in Tier 2) + - **Why**: Fills gaps, but adds to skill count + - **Note**: Consider based on actual usage patterns + +9. **Enhanced Status Line** (2-3 hours) + - Port statusline script + - Add cost tracking + - Create setup command + - **Why**: Nice quality-of-life, but not essential + - **Note**: Platform-specific maintenance + +10. **Additional Hooks** (2-3 hours) + - SubagentLogger + - PostToolUse code change detection + - Analytics tracking + - **Why**: Useful for power users, but not essential + - **Note**: More infrastructure to maintain + +**Impact**: Enhanced capabilities for advanced use cases, better infrastructure + +--- + +## Alternative Approach: Minimal Integration + +If you want the **absolute minimum** valuable additions: + +### Phase 1: Knowledge Only (2-3 hours) +- DISCOVERIES.md template +- Decision tracking README +- Update 2-3 skills to reference them + +**Impact**: Immediate knowledge management improvement with minimal effort + +### Phase 2: Philosophy Only (1-2 hours) +- Port two philosophy docs +- Add to SessionStart context +- Reference from 3-5 key skills + +**Impact**: Consistent decision-making framework + +### Phase 3: Transcripts Only (3-4 hours) +- PreCompact hook +- /transcripts command + +**Impact**: Never lose context + +**Total Minimal Integration**: 6-9 hours for biggest wins + +--- + +## Implementation Risks & Mitigation + +### Risk 1: Scope Creep +**Risk**: Trying to implement everything, project becomes overwhelming +**Mitigation**: +- Start with Tier 1 only (4-6 hours) +- Validate value before proceeding +- Be willing to abandon low-value additions + +### Risk 2: Maintenance Burden +**Risk**: Adding infrastructure that requires ongoing maintenance +**Mitigation**: +- Prefer documentation over code (philosophy docs) +- Use simple, stable patterns (DISCOVERIES template) +- Avoid complex hooks unless high value (PreCompact yes, analytics maybe not) + +### Risk 3: Philosophical Drift +**Risk**: Amplifier's agent-based approach conflicts with skills philosophy +**Mitigation**: +- Extract patterns, not architectures +- Maintain skills-based auto-activation +- Don't port agents directly + +### Risk 4: User Adoption +**Risk**: New features/patterns not used by users +**Mitigation**: +- Start with infrastructure (transcripts, philosophy) +- Make skills reference new systems automatically +- Provide clear examples and documentation + +### Risk 5: Skill Proliferation +**Risk**: Too many skills, hard to discover/maintain +**Mitigation**: +- Only add skills that fill real gaps +- Consider enhancing existing skills vs new ones +- Keep skill count reasonable (38 max vs current 33) + +--- + +## Trade-off Analysis + +### What to Definitely Include + +✅ **DISCOVERIES.md**: Zero downside, high value, minimal effort + +✅ **Decision Tracking**: Proven pattern, addresses real pain point + +✅ **Philosophy Docs**: Aligns with existing values, provides framework + +✅ **PreCompact Transcripts**: Solves major pain point (context loss) + +### What to Carefully Consider + +⚠️ **Full DDD Workflow**: Powerful but heavyweight, maybe too much structure + +⚠️ **Defensive Utilities**: High value for custom tools, but adds Python dependencies + +⚠️ **5 New Skills**: Fills gaps but increases skill count significantly + +⚠️ **Multiple Hooks**: Each hook is maintenance burden, prioritize carefully + +### What to Probably Skip + +❌ **Direct Agent Porting**: Wrong architectural approach for Superpowers + +❌ **Complex Analytics**: Maintenance burden, unclear value + +❌ **Platform-Specific Tools**: Statusline is nice but needs multi-platform support + +--- + +## Recommended Implementation Sequence + +### Sequence A: Fastest Value (Recommended) + +1. **Week 1**: Tier 1 only (4-6 hours) + - DISCOVERIES.md + integration + - Decision tracking + skill + - Philosophy docs + - **Validate value before proceeding** + +2. **Week 2**: Tier 2 based on Week 1 success (8-12 hours) + - PreCompact transcripts (highest priority from Tier 2) + - Lightweight DDD patterns + - SessionStart enhancements + +3. **Week 3+**: Tier 3 based on actual needs + - Only add what's actually needed + - User feedback drives priorities + +### Sequence B: Infrastructure First + +1. **Phase 1**: Hooks (3-4 hours) + - PreCompact transcripts + - SessionStart enhancements + +2. **Phase 2**: Knowledge (2-3 hours) + - DISCOVERIES.md + - Decision tracking + +3. **Phase 3**: Content (1-2 hours) + - Philosophy docs + +4. **Phase 4**: Skills (as needed) + - New skills based on usage + +### Sequence C: Minimal/Conservative + +1. **Just the docs** (2-3 hours) + - DISCOVERIES.md template + - Decision tracking README + - Two philosophy docs + +2. **Wait and see** + - Use for a month + - Identify actual gaps + - Add infrastructure only if needed + +--- + +## Success Metrics + +### Tier 1 Success Metrics +- DISCOVERIES.md has 5+ useful entries after 2 weeks +- 2-3 decision records created for real decisions +- Philosophy docs referenced in conversation at least once per session +- Reduced repeated problem-solving (subjective but observable) + +### Tier 2 Success Metrics +- Zero context loss complaints after implementing transcripts +- Plans include artifact creation +- Execution includes approval gates +- SessionStart shows useful context + +### Tier 3 Success Metrics +- New skills actually activated automatically +- Defensive utilities used in custom tools (if applicable) +- Status line referenced by user +- Analytics provide useful insights + +--- + +## Conclusion + +### Summary of Findings + +The Amplifier project demonstrates a **mature, production-tested ecosystem** around Claude Code with excellent transferable patterns. The highest-value additions focus on: + +1. **Knowledge Management** (DISCOVERIES, decisions) - Prevents repeated work +2. **Philosophy Documentation** - Guides consistent decision-making +3. **Infrastructure** (transcripts, hooks) - Enhances all skills +4. **Workflow Patterns** (lightweight DDD) - Improves planning/execution + +### Key Strategic Insight + +**Extract patterns and principles, not architectures.** + +Amplifier's agent-based approach is powerful but heavy. Superpowers' skills-based approach is elegant and automatic. The best path forward is: +- ✅ Port knowledge systems (DISCOVERIES, decisions) +- ✅ Port philosophy and patterns (docs, principles) +- ✅ Port high-value infrastructure (transcripts) +- ✅ Extract agent patterns into skills (analysis-first, proactive triggers) +- ❌ Don't port agent architecture directly + +### Recommended Starting Point + +**Start with Tier 1** (4-6 hours): +1. DISCOVERIES.md pattern +2. Decision tracking system +3. Philosophy documentation + +**Then evaluate**: +- If valuable, proceed to Tier 2 (PreCompact transcripts, lightweight DDD) +- If not valuable, stop or adjust + +### Expected Impact + +With Tier 1 alone: +- 30% reduction in repeated problem-solving +- Better decision continuity +- Consistent decision-making framework +- **Total effort**: 4-6 hours +- **ROI**: High + +With Tiers 1+2: +- All Tier 1 benefits +- Never lose context to compaction +- Better planning/execution workflows +- Enhanced session setup +- **Total effort**: 12-18 hours +- **ROI**: Very High + +--- + +## Next Steps + +1. **Review this analysis** and decide which tier to implement +2. **Choose implementation sequence** (A, B, or C) +3. **Start with smallest viable addition** (Tier 1 recommended) +4. **Validate value** before proceeding to next tier +5. **Iterate based on actual usage** rather than speculation + +--- + +## Appendix: File Changes Summary + +### Tier 1 Files (New) +- `DISCOVERIES.md` (template) +- `decisions/README.md` (template + 3-5 examples) +- `docs/IMPLEMENTATION_PHILOSOPHY.md` +- `docs/MODULAR_DESIGN_PHILOSOPHY.md` +- `skills/architectural-decision-making/SKILL.md` + +### Tier 1 Files (Modified) +- `skills/systematic-debugging/SKILL.md` (reference DISCOVERIES) +- `skills/when-stuck/SKILL.md` (reference DISCOVERIES) +- `skills/writing-skills/SKILL.md` (reference decision tracking) +- `skills/using-superpowers/SKILL.md` (mention knowledge systems) +- `.claude/tools/hook_session_start.py` (load philosophy docs) + +### Tier 2 Files (New) +- `.claude/tools/hook_precompact.py` +- `.claude/commands/transcripts.md` +- `skills/document-first-development/SKILL.md` +- `.data/transcripts/README.md` + +### Tier 2 Files (Modified) +- `skills/writing-plans/SKILL.md` (artifact creation) +- `skills/executing-plans/SKILL.md` (approval gates) +- `skills/documentation-management/SKILL.md` (retcon writing) +- `.claude/settings.json` (add PreCompact hook) +- `.claude/tools/hook_session_start.py` (project status) + +### Tier 3 Files (New) +- `tools/defensive_patterns/*.py` (5 utilities) +- `skills/defensive-llm-integration/SKILL.md` +- `skills/modular-construction/SKILL.md` +- `skills/requirement-clarification/SKILL.md` +- `skills/contract-first-design/SKILL.md` +- `skills/knowledge-management/SKILL.md` +- `.claude/tools/statusline-enhanced.sh` +- `.claude/commands/statusline.md` +- `.claude/tools/subagent-logger.py` +- `.claude/tools/hook_post_tool_use.py` + +--- + +**Document Version**: 1.1 +**Last Updated**: 2025-11-02 +**Author**: Claude (Sonnet 4.5) +**Reviewers**: [To be added after review] +**Change Log**: +- v1.0 (2025-10-23): Initial comprehensive analysis +- v1.1 (2025-11-02): Updated with changes from both projects, confirmed recommendations remain valid diff --git a/docs/decisions/001-adopt-knowledge-management.md b/docs/decisions/001-adopt-knowledge-management.md new file mode 100644 index 000000000..f06d93f46 --- /dev/null +++ b/docs/decisions/001-adopt-knowledge-management.md @@ -0,0 +1,57 @@ +# [DECISION-001] Adopt Knowledge Management Patterns + +**Status**: Active +**Date**: 2025-11-03 + +## Context + +Working solo and in teams, we need to track architectural decisions and non-obvious problem solutions. The `mem` system works well for personal knowledge but doesn't provide: + +- Team visibility (others can't see decisions/discoveries) +- Git history (no tracking of when/why decisions changed) +- Discoverability (team members don't know what's been solved) + +## Decision + +Adopt opt-in knowledge management patterns: + +- Architecture Decision Records (ADRs) in `docs/decisions/` +- DISCOVERIES pattern in `docs/discoveries/DISCOVERIES.md` + +These complement `mem` (personal) with project-level (team) documentation. + +## Rationale + +- **Opt-in**: Only enable in projects where valuable, no forcing on teams +- **Complements mem**: Use mem for solo work, files for team sharing +- **Git-tracked**: Decisions and discoveries preserved in version control +- **Discoverable**: Team members can browse `docs/` to learn project context + +Follows patterns from Microsoft Amplifier project, adapted for our needs. + +## Alternatives Considered + +- **Just use mem**: Rejected - doesn't share with team, not in git +- **Force in all projects**: Rejected - violates autonomy, creates empty dirs everywhere +- **Separate skill**: Rejected - better to integrate into existing workflows + +## Consequences + +**Positive:** + +- ✅ Project-level knowledge preserved +- ✅ Team members can discover decisions/solutions +- ✅ Git history tracks evolution of thinking +- ✅ Skills automatically use when present + +**Negative/Risks:** + +- ⚠️ Another system to maintain (but opt-in mitigates) +- ⚠️ Need discipline to document (but skills prompt) +- ⚠️ Template versioning (embedded in slash command) + +## Review Triggers + +- [ ] If team adoption is low after 3 months +- [ ] If maintenance burden becomes significant +- [ ] If mem system evolves to cover team use cases diff --git a/docs/decisions/README.md b/docs/decisions/README.md new file mode 100644 index 000000000..2db75f344 --- /dev/null +++ b/docs/decisions/README.md @@ -0,0 +1,95 @@ +# Architecture Decision Records (ADRs) + +This directory tracks significant architectural and design decisions for the project. + +## When to Create an ADR + +Create a decision record when: + +- Making architectural choices (patterns, frameworks, approaches) +- Choosing between multiple valid approaches +- Making decisions that will be hard to reverse +- Establishing project conventions or standards +- Making trade-offs that future developers should understand + +**Use `mem` for quick decision tracking in solo work.** + +**Use ADRs when:** + +- Decisions affect team members +- Complex decisions requiring full justification +- Decisions you want in git history +- Formal documentation is valuable + +## ADR Template + +Copy this template for new decisions: + +```markdown +# [DECISION-NNN] Title + +**Status**: Active | Deprecated | Superseded +**Date**: YYYY-MM-DD + +## Context + +Why was this decision needed? What problem are we solving? + +## Decision + +What did we decide to do? + +## Rationale + +Why this approach over alternatives? + +## Alternatives Considered + +What other options did we evaluate? + +- **Option A**: Description and why rejected +- **Option B**: Description and why rejected + +## Consequences + +**Positive:** + +- ✅ Benefit 1 +- ✅ Benefit 2 + +**Negative/Risks:** + +- ⚠️ Trade-off 1 +- ⚠️ Trade-off 2 + +## Review Triggers + +When should we reconsider this decision? + +- [ ] Condition 1 +- [ ] Condition 2 +``` + +## Naming Convention + +Files: `NNN-short-description.md` where NNN is zero-padded number (001, 002, etc.) + +Examples: + +- `001-use-typescript-for-frontend.md` +- `002-adopt-microservices-architecture.md` + +## Updating Status + +When revisiting decisions: + +- **Deprecated**: No longer recommended, but still in use +- **Superseded**: Replaced by another decision (link to it) + +## Tips + +- Write ADRs when fresh - capture context while it's clear +- Include specific examples and code snippets +- Link to relevant issues, PRs, or documentation +- Update status when circumstances change +- One decision per ADR (don't bundle) diff --git a/docs/discoveries/DISCOVERIES.md b/docs/discoveries/DISCOVERIES.md new file mode 100644 index 000000000..488feb677 --- /dev/null +++ b/docs/discoveries/DISCOVERIES.md @@ -0,0 +1,44 @@ +# Discoveries + +This document tracks non-obvious problems, their root causes, solutions, and prevention strategies. Check here before debugging similar issues. + +**Use `mem` for personal discovery tracking in solo work.** + +**Use this file when:** + +- Project-specific issues that affect team members +- Problems you want in git history +- Issues requiring structured documentation +- Collective learning is valuable + +## Template + +Copy this template for new entries: + +```markdown +## Issue Title (YYYY-MM-DD) + +### Issue + +Clear description of the problem observed. Include symptoms and error messages. + +### Root Cause + +What actually caused it? Not just symptoms - trace to the source. + +### Solution + +How was it fixed? Specific steps, code changes, or configuration updates. + +### Prevention + +How to avoid this in the future? Patterns, checks, validation, or practices to adopt. +``` + +--- + +## Discoveries + +_No discoveries yet. This section will grow as we encounter and solve non-obvious problems._ + + diff --git a/docs/plans/2025-11-03-knowledge-management-implementation-plan.md b/docs/plans/2025-11-03-knowledge-management-implementation-plan.md new file mode 100644 index 000000000..64f4a0b07 --- /dev/null +++ b/docs/plans/2025-11-03-knowledge-management-implementation-plan.md @@ -0,0 +1,884 @@ +# Knowledge Management Integration Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Integrate ADR and DISCOVERIES patterns from Amplifier analysis as opt-in knowledge management system + +**Architecture:** Slash command with embedded templates creates structure, 9 skills integrate with opt-in checks + +**Tech Stack:** Markdown documentation, bash/git for verification + +--- + +## Existing Patterns Survey + +**Similar features:** +- Existing slash commands: `commands/brainstorm.md`, `commands/execute-plan.md`, `commands/write-plan.md` +- Skill integration pattern: Skills reference other patterns (e.g., TDD, git-worktrees) +- Opt-in pattern: Skills check for presence before using + +**Conventions to follow:** +- Commands: Markdown files with clear instructions for agents +- Skill modifications: Add sections that check "if exists" +- Commit messages: Conventional commits format +- Documentation: Clear examples and templates + +--- + +## Task 1: Create Slash Command with Embedded Templates + +**Files:** +- Create: `commands/setup-knowledge-management.md` + +**Step 1: Create command file with full content** + +Create `commands/setup-knowledge-management.md` with: +- Overview section +- Pre-flight checks instructions +- Decision logic for conflicts +- Setup steps with embedded ADR template +- Setup steps with embedded DISCOVERIES template +- Verification steps + +Full content: + +```markdown +# Setup Knowledge Management + +Set up ADR (Architecture Decision Records) and DISCOVERIES pattern for this project. + +## Overview + +This command creates an opt-in knowledge management structure: +- `docs/decisions/` for Architecture Decision Records +- `docs/discoveries/` for tracking non-obvious problems and solutions + +These complement personal `mem` usage with project-level, git-tracked documentation. + +## Pre-flight Checks + +BEFORE creating anything, check: + +1. Does `docs/decisions/` exist? +2. Does `docs/discoveries/` exist? +3. Does `docs/decisions/README.md` exist? +4. Does `docs/discoveries/DISCOVERIES.md` exist? + +Commands: +```bash +ls -la docs/decisions/ 2>/dev/null +ls -la docs/discoveries/ 2>/dev/null +test -f docs/decisions/README.md && echo "README exists" +test -f docs/discoveries/DISCOVERIES.md && echo "DISCOVERIES exists" +``` + +## Decision Logic + +### If ALL checks are clean (nothing exists): +Proceed with "Setup Steps" below. + +### If ANY already exist: +**STOP immediately.** + +Report what exists: +```bash +echo "Found existing structure:" +test -d docs/decisions && echo " - docs/decisions/" +test -d docs/discoveries && echo " - docs/discoveries/" +test -f docs/decisions/README.md && echo " - docs/decisions/README.md" +test -f docs/discoveries/DISCOVERIES.md && echo " - docs/discoveries/DISCOVERIES.md" +``` + +Present options to user: +1. **Skip setup** - Keep existing structure, don't modify +2. **Create only missing pieces** - Add what's missing, preserve what exists +3. **Show templates** - Display what would be created for manual review + +Wait for user to choose before proceeding. + +## Setup Steps + +Only execute if pre-flight checks are clean. + +### Step 1: Create directory structure + +```bash +mkdir -p docs/decisions +mkdir -p docs/discoveries +``` + +### Step 2: Create docs/decisions/README.md + +Create file with this exact content: + +```markdown +# Architecture Decision Records (ADRs) + +This directory tracks significant architectural and design decisions for the project. + +## When to Create an ADR + +Create a decision record when: +- Making architectural choices (patterns, frameworks, approaches) +- Choosing between multiple valid approaches +- Making decisions that will be hard to reverse +- Establishing project conventions or standards +- Making trade-offs that future developers should understand + +**Use `mem` for quick decision tracking in solo work.** + +**Use ADRs when:** +- Decisions affect team members +- Complex decisions requiring full justification +- Decisions you want in git history +- Formal documentation is valuable + +## ADR Template + +Copy this template for new decisions: + +\`\`\`markdown +# [DECISION-NNN] Title + +**Status**: Active | Deprecated | Superseded +**Date**: YYYY-MM-DD + +## Context +Why was this decision needed? What problem are we solving? + +## Decision +What did we decide to do? + +## Rationale +Why this approach over alternatives? + +## Alternatives Considered +What other options did we evaluate? +- **Option A**: Description and why rejected +- **Option B**: Description and why rejected + +## Consequences + +**Positive:** +- ✅ Benefit 1 +- ✅ Benefit 2 + +**Negative/Risks:** +- ⚠️ Trade-off 1 +- ⚠️ Trade-off 2 + +## Review Triggers +When should we reconsider this decision? +- [ ] Condition 1 +- [ ] Condition 2 +\`\`\` + +## Naming Convention + +Files: `NNN-short-description.md` where NNN is zero-padded number (001, 002, etc.) + +Examples: +- `001-use-typescript-for-frontend.md` +- `002-adopt-microservices-architecture.md` + +## Updating Status + +When revisiting decisions: +- **Deprecated**: No longer recommended, but still in use +- **Superseded**: Replaced by another decision (link to it) + +## Tips + +- Write ADRs when fresh - capture context while it's clear +- Include specific examples and code snippets +- Link to relevant issues, PRs, or documentation +- Update status when circumstances change +- One decision per ADR (don't bundle) +``` + +### Step 3: Create docs/discoveries/DISCOVERIES.md + +Create file with this exact content: + +```markdown +# Discoveries + +This document tracks non-obvious problems, their root causes, solutions, and prevention strategies. Check here before debugging similar issues. + +**Use `mem` for personal discovery tracking in solo work.** + +**Use this file when:** +- Project-specific issues that affect team members +- Problems you want in git history +- Issues requiring structured documentation +- Collective learning is valuable + +## Template + +Copy this template for new entries: + +\`\`\`markdown +## Issue Title (YYYY-MM-DD) + +### Issue +Clear description of the problem observed. Include symptoms and error messages. + +### Root Cause +What actually caused it? Not just symptoms - trace to the source. + +### Solution +How was it fixed? Specific steps, code changes, or configuration updates. + +### Prevention +How to avoid this in the future? Patterns, checks, validation, or practices to adopt. +\`\`\` + +--- + +## Discoveries + +*No discoveries yet. This section will grow as we encounter and solve non-obvious problems.* + + +``` + +### Step 4: Verify structure created + +Run verification commands: + +```bash +echo "Verifying structure..." +ls -la docs/decisions/ +ls -la docs/discoveries/ +echo "" +echo "Verifying file contents..." +wc -l docs/decisions/README.md +wc -l docs/discoveries/DISCOVERIES.md +``` + +Expected output: +- Both directories exist +- README.md has ~80+ lines +- DISCOVERIES.md has ~40+ lines + +### Step 5: Optional - Create example ADR + +Ask user: "Would you like to create an example ADR (001-adopt-knowledge-management.md) documenting this decision to adopt these patterns?" + +If yes, create `docs/decisions/001-adopt-knowledge-management.md`: + +```markdown +# [DECISION-001] Adopt Knowledge Management Patterns + +**Status**: Active +**Date**: YYYY-MM-DD + +## Context + +Working solo and in teams, we need to track architectural decisions and non-obvious problem solutions. The `mem` system works well for personal knowledge but doesn't provide: +- Team visibility (others can't see decisions/discoveries) +- Git history (no tracking of when/why decisions changed) +- Discoverability (team members don't know what's been solved) + +## Decision + +Adopt opt-in knowledge management patterns: +- Architecture Decision Records (ADRs) in `docs/decisions/` +- DISCOVERIES pattern in `docs/discoveries/DISCOVERIES.md` + +These complement `mem` (personal) with project-level (team) documentation. + +## Rationale + +- **Opt-in**: Only enable in projects where valuable, no forcing on teams +- **Complements mem**: Use mem for solo work, files for team sharing +- **Git-tracked**: Decisions and discoveries preserved in version control +- **Discoverable**: Team members can browse `docs/` to learn project context + +Follows patterns from Microsoft Amplifier project, adapted for our needs. + +## Alternatives Considered + +- **Just use mem**: Rejected - doesn't share with team, not in git +- **Force in all projects**: Rejected - violates autonomy, creates empty dirs everywhere +- **Separate skill**: Rejected - better to integrate into existing workflows + +## Consequences + +**Positive:** +- ✅ Project-level knowledge preserved +- ✅ Team members can discover decisions/solutions +- ✅ Git history tracks evolution of thinking +- ✅ Skills automatically use when present + +**Negative/Risks:** +- ⚠️ Another system to maintain (but opt-in mitigates) +- ⚠️ Need discipline to document (but skills prompt) +- ⚠️ Template versioning (embedded in slash command) + +## Review Triggers +- [ ] If team adoption is low after 3 months +- [ ] If maintenance burden becomes significant +- [ ] If mem system evolves to cover team use cases +``` + +### Step 6: Stage and commit + +```bash +git add docs/ +git commit -m "docs: add knowledge management structure (ADR + DISCOVERIES)" +``` + +## Completion + +Structure created successfully. Skills will automatically detect and use these patterns when present. + +**Next steps:** +- Document architectural decisions as they're made +- Add discoveries when solving non-obvious problems +- Share with team members +``` + +**Step 2: Verify file created** + +```bash +ls -la commands/setup-knowledge-management.md +wc -l commands/setup-knowledge-management.md +``` + +Expected: File exists with ~250+ lines + +**Step 3: Commit** + +```bash +git add commands/setup-knowledge-management.md +git commit -m "feat(commands): add setup-knowledge-management slash command" +``` + +--- + +## Task 2: Update systematic-debugging Skill + +**Files:** +- Modify: `skills/systematic-debugging/SKILL.md` + +**Step 1: Read current file** + +```bash +cat skills/systematic-debugging/SKILL.md +``` + +**Step 2: Add discovery documentation section** + +After "Phase 4: Implementation", Step 4 "If Fix Doesn't Work", add new Step 5: + +```markdown +5. **Document Discovery (if applicable)** + + **WHEN root cause was non-obvious or could recur:** + + Check if `docs/discoveries/DISCOVERIES.md` exists: + + ```bash + test -f docs/discoveries/DISCOVERIES.md && echo "File exists" + ``` + + **If file exists:** + - Document the Issue, Root Cause, Solution, Prevention + - Help future developers (including yourself) skip this investigation + - Add entry using template from DISCOVERIES.md + + **If file doesn't exist:** + - Use `mem add "Discovery: [issue] caused by [root cause]. Fixed by [solution]" --tags "discovery,bug,project"` + - Personal reference for future debugging +``` + +**Step 3: Verify changes** + +```bash +grep -A 10 "Document Discovery" skills/systematic-debugging/SKILL.md +``` + +Expected: New section appears with both file-exists and fallback paths + +**Step 4: Commit** + +```bash +git add skills/systematic-debugging/SKILL.md +git commit -m "feat(skills): integrate discoveries pattern in systematic-debugging" +``` + +--- + +## Task 3: Update root-cause-tracing Skill + +**Files:** +- Modify: `skills/root-cause-tracing/SKILL.md` + +**Step 1: Add documenting discoveries section** + +After "Real Example: Empty projectDir" section, add new section: + +```markdown +## Documenting Discoveries + +After tracing to source and fixing: + +**Check if project uses discoveries pattern:** + +```bash +test -f docs/discoveries/DISCOVERIES.md && echo "Discoveries file exists" +``` + +**If `docs/discoveries/DISCOVERIES.md` exists:** +- Document the complete trace path +- Record the root cause discovered +- Describe the solution applied +- Add prevention guidance +- Help others recognize this pattern faster + +**If file doesn't exist:** +- Use `mem add "Root cause trace: [symptom] → [immediate cause] → [source]. Fixed at [location]" --tags "discovery,trace,project"` +- Store for personal reference in future debugging +``` + +**Step 2: Verify changes** + +```bash +grep -A 5 "Documenting Discoveries" skills/root-cause-tracing/SKILL.md +``` + +**Step 3: Commit** + +```bash +git add skills/root-cause-tracing/SKILL.md +git commit -m "feat(skills): integrate discoveries pattern in root-cause-tracing" +``` + +--- + +## Task 4: Update when-stuck Skill + +**Files:** +- Modify: `skills/when-stuck/SKILL.md` + +**Step 1: Add check known issues step** + +In "Process" section, before step 1, add step 0: + +```markdown +0. **Check Known Issues** (if applicable) + + Before dispatching to problem-solving techniques, check if this problem has been solved before: + + ```bash + test -f docs/discoveries/DISCOVERIES.md && echo "Check DISCOVERIES file" + ``` + + **If `docs/discoveries/DISCOVERIES.md` exists:** + - Read through discoveries for similar problems + - Search for keywords related to your stuck-ness + - May find solution without full investigation + + **Otherwise:** + - Try `mem search semantic "stuck on [describe problem]"` + - May find past solutions from your personal knowledge +``` + +**Step 2: Verify changes** + +```bash +grep -B 2 -A 10 "Check Known Issues" skills/when-stuck/SKILL.md +``` + +**Step 3: Commit** + +```bash +git add skills/when-stuck/SKILL.md +git commit -m "feat(skills): integrate discoveries pattern in when-stuck" +``` + +--- + +## Task 5: Update predict-issues Skill + +**Files:** +- Modify: `skills/predict-issues/SKILL.md` + +**Step 1: Update tracking predictions section** + +Replace "Tracking Predictions" section with: + +```markdown +## Tracking Predictions + +After analysis, ask user how to track findings: + +**Available options:** + +- **decisions/** - Create ADR for architectural choices (if `docs/decisions/` exists) +- **discoveries/** - Document known issues and prevention (if `docs/discoveries/DISCOVERIES.md` exists) +- **Memory** - Store risk assessments using `mem add` for personal reference +- **TodoWrite** - Create structured task list for systematic review +- **Summary only** - Provide report without creating artifacts + +Check which options are available: + +```bash +test -d docs/decisions && echo "ADR available" +test -f docs/discoveries/DISCOVERIES.md && echo "DISCOVERIES available" +``` + +Present only available options to user. +``` + +**Step 2: Verify changes** + +```bash +grep -A 15 "Tracking Predictions" skills/predict-issues/SKILL.md +``` + +**Step 3: Commit** + +```bash +git add skills/predict-issues/SKILL.md +git commit -m "feat(skills): integrate ADR and discoveries in predict-issues" +``` + +--- + +## Task 6: Update documentation-management Skill + +**Files:** +- Modify: `skills/documentation-management/SKILL.md` + +**Step 1: Update documentation types section** + +In "Documentation Types" section, add after existing types: + +```markdown +- **ADR** (decisions/): Architecture decisions with rationale (if `docs/decisions/` exists) +- **DISCOVERIES** (discoveries/): Known issues and solutions (if `docs/discoveries/DISCOVERIES.md` exists) +``` + +**Step 2: Update change type patterns table** + +In "Update Patterns by Change Type" table, add new row: + +```markdown +| **Architecture change** | README architecture section, CHANGELOG, ADR in decisions/ (if exists) | +``` + +**Step 3: Verify changes** + +```bash +grep "ADR\|DISCOVERIES" skills/documentation-management/SKILL.md +``` + +Expected: Both patterns mentioned in types and table + +**Step 4: Commit** + +```bash +git add skills/documentation-management/SKILL.md +git commit -m "feat(skills): integrate ADR and discoveries in documentation-management" +``` + +--- + +## Task 7: Update writing-plans Skill + +**Files:** +- Modify: `skills/writing-plans/SKILL.md` + +**Step 1: Update survey existing patterns section** + +In "Survey Existing Patterns" section, after step 1 "Find similar features", add step 2: + +```markdown +2. **Check decisions**: If `docs/decisions/` exists, review relevant ADRs for architectural context + ```bash + test -d docs/decisions && ls docs/decisions/*.md + ``` + Read ADRs that relate to the feature being planned. +``` + +Renumber subsequent steps (current 2→3, 3→4, 4→5). + +**Step 2: Verify changes** + +```bash +grep -A 3 "Check decisions" skills/writing-plans/SKILL.md +``` + +**Step 3: Commit** + +```bash +git add skills/writing-plans/SKILL.md +git commit -m "feat(skills): integrate decisions pattern in writing-plans" +``` + +--- + +## Task 8: Update brainstorming Skill + +**Files:** +- Modify: `skills/brainstorming/SKILL.md` + +**Step 1: Update Prep section** + +In "Prep: Autonomous Recon", first bullet point, change from: +```markdown +- Use existing tools (file browsing, docs, git history, tests) to understand... +``` + +To: +```markdown +- Use existing tools (file browsing, docs, git history, tests, decisions/) to understand current project state before asking anything. +``` + +**Step 2: Update Phase 1 section** + +In "Phase 1: Understanding", add after first bullet: + +```markdown +- Check `docs/decisions/` (if exists) for relevant architectural decisions + ```bash + test -d docs/decisions && fd . docs/decisions + ``` +``` + +**Step 3: Update Phase 4 section** + +In "Phase 4: Design Documentation", after "Commit the design document to git before proceeding", add: + +```markdown + +**If significant architectural choice was made:** + +Check if project uses ADR pattern: +```bash +test -d docs/decisions && echo "ADR available" +``` + +If available, consider creating ADR to document the architectural decision with full context, alternatives considered, and rationale. +``` + +**Step 4: Verify changes** + +```bash +grep "decisions/" skills/brainstorming/SKILL.md | head -5 +``` + +Expected: Three mentions in Prep, Phase 1, and Phase 4 + +**Step 5: Commit** + +```bash +git add skills/brainstorming/SKILL.md +git commit -m "feat(skills): integrate decisions pattern in brainstorming" +``` + +--- + +## Task 9: Update enhancing-superpowers Skill + +**Files:** +- Modify: `skills/enhancing-superpowers/SKILL.md` + +**Step 1: Add decision documentation integration type** + +In "Integration Approaches by Type" section, after Type 5, add Type 6: + +```markdown +### Type 6: Decision Documentation + +**Example:** Deciding to add/reject external patterns + +**Approach:** + +1. Check if project uses ADR pattern: + ```bash + test -d docs/decisions && echo "ADR available" + ``` +2. **If exists**: Create ADR documenting integration decision with context, rationale, alternatives +3. **Otherwise**: Use `mem add "Integration decision: [what] because [why]. Alternatives: [rejected options]" --tags "decision,integration"` +4. Reference in related skills or documentation + +**Avoid:** Making major decisions without documenting rationale +``` + +**Step 2: Verify changes** + +```bash +grep -A 15 "Type 6: Decision Documentation" skills/enhancing-superpowers/SKILL.md +``` + +**Step 3: Commit** + +```bash +git add skills/enhancing-superpowers/SKILL.md +git commit -m "feat(skills): add decision documentation pattern in enhancing-superpowers" +``` + +--- + +## Task 10: Update extracting-patterns-from-projects Skill + +**Files:** +- Modify: `skills/extracting-patterns-from-projects/SKILL.md` + +**Step 1: Update comprehensive write-up section** + +In "6. Comprehensive Write-up" section, after the list of required sections, add: + +```markdown + +**After write-up:** + +Check if project uses ADR pattern: +```bash +test -d docs/decisions && echo "ADR available" +``` + +**If this is a major integration decision:** +- **If ADR available**: Create ADR documenting the decision to integrate (or not integrate) patterns +- **Otherwise**: Store decision rationale with `mem add "Pattern extraction decision: [what] because [why]" --tags "decision,patterns"` + +Major integrations warrant formal decision documentation. +``` + +**Step 2: Verify changes** + +```bash +grep -A 10 "After write-up" skills/extracting-patterns-from-projects/SKILL.md +``` + +**Step 3: Commit** + +```bash +git add skills/extracting-patterns-from-projects/SKILL.md +git commit -m "feat(skills): integrate decisions pattern in extracting-patterns-from-projects" +``` + +--- + +## Task 11: Test Setup Command in Superpowers Repo + +**Files:** +- Will create: `docs/decisions/`, `docs/discoveries/` + +**Step 1: Run the slash command** + +From worktree root: + +```bash +# Simulate what agent would do after reading command +mkdir -p docs/decisions +mkdir -p docs/discoveries +``` + +Then manually create the two files by copying content from the command template. + +**Step 2: Verify structure** + +```bash +ls -la docs/decisions/ +ls -la docs/discoveries/ +cat docs/decisions/README.md | head -20 +cat docs/discoveries/DISCOVERIES.md | head -20 +``` + +Expected: Both directories exist with README files + +**Step 3: Create ADR 001** + +Create `docs/decisions/001-adopt-knowledge-management.md` documenting this integration decision. Use template from command, fill in actual date and context. + +**Step 4: Verify all files** + +```bash +fd . docs +``` + +Expected output: +``` +docs/decisions/README.md +docs/decisions/001-adopt-knowledge-management.md +docs/discoveries/DISCOVERIES.md +docs/plans/2025-11-03-knowledge-management-integration-design.md +docs/plans/2025-11-03-knowledge-management-implementation-plan.md +``` + +**Step 5: Commit structure** + +```bash +git add docs/ +git commit -m "docs: add knowledge management structure to superpowers + +- Create docs/decisions/ with README and ADR template +- Create docs/discoveries/ with DISCOVERIES template +- Document decision to adopt pattern in ADR 001 +- Superpowers now dogfoods own pattern" +``` + +--- + +## Task 12: Final Verification + +**Step 1: Verify all changes staged** + +```bash +git status +``` + +Expected: No uncommitted changes (everything already committed in individual tasks) + +**Step 2: Review commit history** + +```bash +git log --oneline -12 +``` + +Expected: 11 commits (1 command + 9 skills + 1 structure + 1 verification) + +**Step 3: Verify skills reference patterns correctly** + +```bash +grep -r "docs/decisions" skills/ | wc -l +grep -r "docs/discoveries" skills/ | wc -l +``` + +Expected: Multiple matches (at least 5 for decisions, at least 4 for discoveries) + +**Step 4: Verify command exists** + +```bash +cat commands/setup-knowledge-management.md | grep "# Setup Knowledge Management" +``` + +Expected: Title appears + +--- + +## Completion Checklist + +After all tasks complete: + +- [ ] Slash command created with embedded templates +- [ ] 9 skills updated with integration points +- [ ] All skills check for presence (opt-in pattern) +- [ ] All skills fall back to mem when absent +- [ ] Structure created in superpowers repo +- [ ] ADR 001 documents this decision +- [ ] All changes committed with conventional commits +- [ ] Verification tests pass + +## Estimated Time + +- Task 1: 30 min (command creation) +- Tasks 2-10: 15 min each = 2h 15min (skill updates) +- Task 11: 30 min (test in superpowers) +- Task 12: 15 min (verification) + +**Total: ~4 hours** diff --git a/docs/plans/2025-11-03-knowledge-management-integration-design.md b/docs/plans/2025-11-03-knowledge-management-integration-design.md new file mode 100644 index 000000000..85afb6414 --- /dev/null +++ b/docs/plans/2025-11-03-knowledge-management-integration-design.md @@ -0,0 +1,278 @@ +# Knowledge Management Integration Design + +**Date**: 2025-11-03 +**Status**: Approved for implementation +**Context**: Integrating ADR and DISCOVERIES patterns from Amplifier analysis (Tier 1) + +--- + +## Goal + +Add opt-in knowledge management system (Architecture Decision Records + DISCOVERIES pattern) to superpowers that complements personal `mem` system with project-level, git-tracked documentation. + +## Architecture + +### Core Components + +1. **Slash Command** (`commands/setup-knowledge-management.md`) + - Embedded templates (source of truth) + - Pre-flight checks for conflicts + - Graceful conflict handling + - Creates structure in any project + +2. **Documentation Structure** (`docs/`) + ``` + docs/ + ├── decisions/ + │ ├── README.md # ADR template and guidelines + │ └── NNN-description.md # Individual decision records + └── discoveries/ + └── DISCOVERIES.md # Known issues and solutions + ``` + +3. **Skill Integration** (9 skills updated) + - Check for structure presence + - Use when available + - Fall back to `mem` when absent + +### Design Decisions + +**Decision: Embedded templates in command** +- Templates live in `commands/setup-knowledge-management.md` +- Plugin distribution only includes `commands/`, not `docs/` +- Single source of truth +- Command creates structure we use (dogfooding) + +**Decision: Opt-in per project** +- Structure doesn't exist by default +- Skills check for presence before using +- Graceful fallback to `mem` +- No forcing on team projects + +**Decision: Under docs/ directory** +- Clear visibility (documentation) +- Standard location for project docs +- Easy for teams to discover + +## Data Flow + +``` +User runs /setup-knowledge-management + ↓ +Agent reads command (embedded templates) + ↓ +Pre-flight checks + ↓ + ├─ Clean → Create structure + │ ↓ + │ Write templates + │ ↓ + │ Optional: Example ADR + │ ↓ + │ Commit + │ + └─ Conflicts → Report & ask + ↓ + User decides + ↓ + Execute choice +``` + +## Components Detail + +### 1. Slash Command Structure + +**File**: `commands/setup-knowledge-management.md` + +**Sections**: +- Overview (what and why) +- Pre-flight checks (detect existing structure) +- Decision logic (handle conflicts) +- Setup steps (create files with embedded content) +- Verification steps (confirm success) + +**Pre-flight checks**: +```bash +- Check: docs/decisions/ exists? +- Check: docs/discoveries/ exists? +- Check: docs/decisions/README.md exists? +- Check: docs/discoveries/DISCOVERIES.md exists? +``` + +**Conflict handling**: +If ANY exist → STOP, report, offer options: +1. Skip setup (keep existing) +2. Create only missing pieces +3. Show templates for manual review + +### 2. Template Content + +**ADR Template** (`docs/decisions/README.md`): +- When to create ADR vs use `mem` +- Template format (Status, Context, Decision, Rationale, Alternatives, Consequences, Review Triggers) +- Naming conventions (NNN-description.md) +- Examples + +**DISCOVERIES Template** (`docs/discoveries/DISCOVERIES.md`): +- What discoveries are +- Template format (Issue, Root Cause, Solution, Prevention) +- When to use file vs `mem` +- Empty discoveries section + +**Optional First ADR** (`docs/decisions/001-adopt-knowledge-management.md`): +- Documents decision to adopt this pattern +- Serves as example +- Ask user if they want it + +### 3. Skill Integration + +**Discovery-focused skills** (4): + +1. **systematic-debugging** - Phase 4, after root cause found: + ```markdown + If docs/discoveries/DISCOVERIES.md exists: + - Document Issue, Root Cause, Solution, Prevention + Otherwise: + - Use mem add for personal reference + ``` + +2. **root-cause-tracing** - After tracing to source: + ```markdown + If docs/discoveries/DISCOVERIES.md exists: + - Document trace path and root cause + Otherwise: + - Use mem add with discovery tag + ``` + +3. **when-stuck** - Before dispatching: + ```markdown + Check docs/discoveries/DISCOVERIES.md for similar problems + Otherwise: mem search semantic + ``` + +4. **predict-issues** - Tracking predictions section: + ```markdown + Options include: + - decisions/ for architectural choices + - discoveries/ for known issues + - mem for personal reference + ``` + +**Decision-focused skills** (5): + +1. **documentation-management** - Add to documentation types: + ```markdown + - ADR (decisions/): Architecture decisions (if exists) + - DISCOVERIES (discoveries/): Known issues (if exists) + ``` + +2. **writing-plans** - Survey existing patterns phase: + ```markdown + Check docs/decisions/ for relevant ADRs + ``` + +3. **brainstorming** - Multiple integration points: + - Prep: Check decisions/ during recon + - Phase 1: Reference decisions/ for context + - Phase 4: Suggest ADR for significant choices + +4. **enhancing-superpowers** - Add integration type: + ```markdown + Type 6: Decision Documentation + - If docs/decisions/ exists: Create ADR + - Otherwise: Use mem + ``` + +5. **extracting-patterns-from-projects** - After write-up: + ```markdown + If docs/decisions/ exists: Create ADR for major integrations + Otherwise: Store in mem + ``` + +**Integration pattern** (all skills): +```markdown +If [structure] exists: + [use pattern] +Otherwise: + [use mem fallback] +``` + +## Testing Strategy + +**Command verification steps**: +1. Verify directories created +2. Verify files created with content +3. Verify git status shows staged files + +**Skill testing**: +1. Test with structure present (uses pattern) +2. Test without structure (falls back to mem) +3. Verify no errors in either case + +## First-Run Experience + +**In superpowers repo**: +1. Run `/setup-knowledge-management` on ourselves +2. Creates our own `docs/` structure +3. Document this decision as ADR 001 +4. Commit all changes together +5. Dogfooding our own pattern + +**In new projects**: +1. User runs `/setup-knowledge-management` +2. Structure created in ~30 seconds +3. Optional: Document adoption decision +4. Skills automatically detect and use + +## Benefits + +**For solo projects**: +- Git-tracked knowledge (survives beyond mem) +- Structured decision documentation +- Clear issue history + +**For team projects**: +- Shared context for decisions +- Collective learning from problems +- Discoverable by all team members + +**For all projects**: +- Opt-in (no forced adoption) +- Graceful fallback to mem +- Natural skill integration + +## Trade-offs + +**Positive**: +- ✅ Complements mem (doesn't replace) +- ✅ Git-tracked (team visibility) +- ✅ Opt-in (no forcing) +- ✅ Skills work with or without it + +**Negative/Risks**: +- ⚠️ Another system to maintain (but opt-in) +- ⚠️ Embedded templates need updating in one place (slash command) +- ⚠️ Users need to remember to document (but skills prompt) + +## Implementation Phases + +**Phase 1**: Create slash command with embedded templates (1 hour) + +**Phase 2**: Update 9 skills with integration points (2-3 hours) + +**Phase 3**: Test and verify (30 minutes) + +**Phase 4**: Run on superpowers itself, create ADR 001 (30 minutes) + +**Phase 5**: Commit everything (10 minutes) + +**Total**: 4-5 hours + +## Success Criteria + +- [ ] Slash command creates clean structure +- [ ] Slash command handles conflicts gracefully +- [ ] All 9 skills reference patterns correctly +- [ ] Skills work with and without structure +- [ ] Superpowers uses its own pattern (dogfooding) +- [ ] Documentation complete and clear diff --git a/docs/upstream-analysis-2025-10-30.md b/docs/upstream-analysis-2025-10-30.md new file mode 100644 index 000000000..66fb227ca --- /dev/null +++ b/docs/upstream-analysis-2025-10-30.md @@ -0,0 +1,443 @@ +# Upstream Changes Analysis: obra/superpowers v3.3.1 + +**Date:** 2025-10-30 +**Analyzer:** Claude (using extracting-patterns-from-projects skill) +**Upstream Range:** main..upstream/main (10 commits) +**Upstream Version:** v3.3.1 + +## Executive Summary + +Upstream has released v3.3.1 with significant improvements to the brainstorming skill and experimental Codex platform support. The most valuable change is the **"Prep: Autonomous Recon" pattern** that encourages research before asking questions—this aligns perfectly with your efficiency and assumption-testing philosophy. + +**Top Recommendations (Tier 1 - 3-4 hours):** + +1. Merge brainstorming skill improvements while preserving your Phase 1.5 and 4.5 additions +2. Skip Codex integration entirely (not relevant to your workflow) +3. Consider the update-checking pattern for future enhancement + +**Key Conflicts:** + +- [skills/brainstorming/SKILL.md](skills/brainstorming/SKILL.md) has substantial changes in both branches +- 50+ files modified in both branches (mostly lowercase name changes) + +## Philosophy Alignment + +| Dimension | obra/superpowers (v3.3.1) | Your Fork | Alignment | +| ------------------------ | ----------------------------------- | ------------------------------- | -------------------------------------------- | +| **Research First** | New: "Prep: Autonomous Recon" phase | Implicit in workflow | ✅ **Strong** - Matches "assumption testing" | +| **Writing Quality** | Strunk & White principles applied | Anti-fluff language policy | ✅ **Strong** - Same goals | +| **Cost Consciousness** | Not emphasized | Core principle | ⚠️ **Moderate** - No conflict | +| **Scope Discipline** | Not emphasized | "Do what's asked, nothing more" | ⚠️ **Moderate** - No conflict | +| **Platform Support** | Multi-platform (Codex added) | Claude Code focused | ⚠️ **Moderate** - Not relevant | +| **Recommendation Style** | New: Lead with preferences | Passive option presentation | ✅ **Strong** - Matches "direct feedback" | +| **Skill Naming** | Lowercase (brainstorming) | Title Case (Brainstorming) | ⚠️ **Cosmetic** - Standardization | + +**Alignment Summary:** Strong philosophical alignment on core principles. Upstream improvements directly support your existing preferences. + +## Pattern Catalog + +### Pattern 1: Proactive Research (Prep: Autonomous Recon) + +**Pattern:** Do autonomous reconnaissance before asking questions +**Problem Solved:** AI asking questions that could be answered by reading existing materials +**Mechanism:** New prep phase - read repo/docs/commits first, form draft model, share understanding, ask only for gaps +**Philosophy Fit:** ✅ **Strong** - Your "assumption testing" principle + +**Trade-offs:** + +| Benefit | Cost | +| --------------------------- | ------------------------------- | +| Fewer interruptions to user | More upfront work for AI | +| Better informed questions | Requires discipline to follow | +| Respects user's time | Could miss nuance in edge cases | + +**Your Custom Addition:** Phase 1.5 (Working with External References) extends this pattern with smart sampling strategies + +### Pattern 2: Recommendation-First Communication + +**Pattern:** Lead with preferred option and rationale when presenting choices +**Problem Solved:** Passive presentation delegates decision-making unnecessarily +**Mechanism:** State recommendation with reasoning, invite disagreement +**Philosophy Fit:** ✅ **Strong** - Your "direct feedback" and efficiency principles + +**Trade-offs:** + +| Benefit | Cost | +| ------------------------------------- | -------------------------------------- | +| More efficient communication | Requires confidence in recommendations | +| Respects user's expertise | Could feel pushy if misapplied | +| Clear position to agree/disagree with | AI must do homework first | + +**Example from upstream:** + +``` +I recommend the direct API approach because it matches existing patterns and minimizes +new infrastructure. Let me know if you see a blocker that pushes us toward the other options. +``` + +### Pattern 3: Writing Clarity (Strunk & White Application) + +**Pattern:** Apply "Elements of Style" principles to skill writing +**Problem Solved:** Skills had needless words and passive constructions +**Mechanism:** Rule 13 (omit needless words), Rule 11 (positive form), Rule 10 (active voice) +**Philosophy Fit:** ✅ **Strong** - Your "anti-fluff language" policy + +**Trade-offs:** + +| Benefit | Cost | +| ----------------------------- | ---------------------------------- | +| More concise documentation | Requires editing discipline | +| Easier to scan and understand | May need multiple passes | +| Professional tone | Could lose personality if overdone | + +**Applied in upstream:** Only to brainstorming skill (commit e3208f1) + +### Pattern 4: Platform Abstraction (Codex Integration) + +**Pattern:** Cross-platform skill system with namespace isolation +**Problem Solved:** Multiple AI coding assistants need access to same skill library +**Mechanism:** Personal vs superpowers namespacing, tool mapping (TodoWrite→update_plan), `.codex/` directory structure +**Philosophy Fit:** ⚠️ **Moderate** - Not relevant to your Claude Code-focused workflow + +**Trade-offs:** + +| Benefit | Cost | +| -------------------------------------- | ----------------------------------------- | +| Broader ecosystem reach | Increased complexity | +| Consistent skills across platforms | Maintenance burden for multiple platforms | +| Namespace isolation prevents conflicts | Platform-specific quirks to handle | + +**Recommendation:** Skip entirely - you're Claude Code-focused + +### Pattern 5: Non-Blocking Update Checks + +**Pattern:** Check for updates with graceful fallback +**Problem Solved:** Users don't know when skills are outdated +**Mechanism:** Git fetch with 3-second timeout in bootstrap, suggests `git pull` if behind +**Philosophy Fit:** ✅ **Strong** - Useful with cost consciousness (timeout protection) + +**Trade-offs:** + +| Benefit | Cost | +| -------------------------------- | ---------------------------------------------- | +| Users stay current | Network dependency (mitigated by timeout) | +| Low friction (just a suggestion) | Could be annoying if frequently behind | +| Graceful failure (no blocking) | Adds ~3 seconds to bootstrap on network issues | + +**Implementation:** In `.codex/superpowers-codex` script (Node.js) + +## Your Custom Enhancements (Not in Upstream) + +### Enhancement 1: Phase 1.5 - Working with External References + +**Your Addition:** Smart sampling strategy when partner references external code/repos +**Value:** Pattern extraction methodology, context mapping guidance +**Status:** Valuable addition - should be preserved + +**Content:** + +- Smart Sampling Strategy (focus on tests, core modules, README) +- Pattern Extraction (conventions, problems solved, design decisions) +- Context Mapping (how contexts differ, what translates) +- Document Insights (when to create reference analysis docs) + +### Enhancement 2: Phase 4.5 - Challenge Your Design + +**Your Addition:** Stress-test design before finalizing +**Value:** Critical thinking checkpoint, catches biases +**Status:** Valuable addition - should be preserved + +**Content:** + +- Steel man the alternatives +- Bias check (familiar/trendy/comfortable) +- Simulate perspectives (ops, future maintainer, security) +- Test cases for the design + +## Three-Tier Recommendations + +### Tier 1: High Value, Low Effort (3-4 hours) + +**1. Merge brainstorming skill improvements (2-3 hours)** + +- **Action:** Cherry-pick upstream brainstorming changes, manually preserve your Phase 1.5 and 4.5 +- **Value:** Proactive research pattern + recommendation-first communication +- **Effort:** Manual merge due to conflicts +- **Risk:** Low - well-tested upstream, your additions are orthogonal + +**Implementation approach:** + +```bash +# Create merge workspace +git worktree add ../claude-settings-brainstorm-merge main + +# In the worktree, manually merge sections: +# - Take upstream: Prep phase, Phase 1, Phase 2, Phase 3 +# - Keep yours: Phase 1.5, Phase 4.5 +# - Take upstream: Key Principles table updates +# - Keep name as "brainstorming" (lowercase) to match upstream convention +``` + +**2. Document decision to skip Codex (15 minutes)** + +- **Action:** Add note to this analysis or CHANGELOG +- **Value:** Clear rationale for future reference +- **Effort:** Minimal +- **Risk:** None + +### Tier 2: Medium Value, Medium Effort (6-8 hours) + +**3. Apply writing clarity pattern to other skills (6-8 hours)** + +- **Action:** Review your custom skills for needless words, passive voice +- **Value:** Consistent quality across skill library +- **Effort:** Requires careful editing of each skill +- **Risk:** Low - improves existing content +- **Priority:** After Tier 1 complete + +**Skills to review:** + +- [skills/extracting-patterns-from-projects/SKILL.md](skills/extracting-patterns-from-projects/SKILL.md) +- [skills/enhancing-superpowers/SKILL.md](skills/enhancing-superpowers/SKILL.md) +- [skills/documentation-management/SKILL.md](skills/documentation-management/SKILL.md) +- Other custom additions + +### Tier 3: Future Exploration (8-12 hours) + +**4. Update checking mechanism (4-6 hours)** + +- **Action:** Research plugin marketplace update notification capabilities +- **Value:** Users stay current with your fork +- **Effort:** Depends on Claude Code plugin API capabilities +- **Risk:** Medium - might not be supported by plugin system +- **Priority:** Only if you notice users falling behind on updates + +**5. Systematic upstream sync process (4-6 hours)** + +- **Action:** Document process for evaluating future upstream changes +- **Value:** Repeatable methodology for staying current +- **Effort:** Documentation + automation scripting +- **Risk:** Low - improves maintainability +- **Priority:** After experiencing this sync cycle once + +## Risk Analysis + +### Risk 1: Merge Conflicts in Brainstorming Skill + +**Likelihood:** High (100% - already exists) +**Impact:** Medium (key skill with substantial changes both sides) +**Mitigation:** + +- Use worktree for isolated merge work +- Manual section-by-section review +- Test with brainstorming skill after merge +- Document merge decisions + +### Risk 2: Diverging from Upstream + +**Likelihood:** Medium (both repos active) +**Impact:** Low (you're maintaining a fork intentionally) +**Mitigation:** + +- Periodic upstream sync reviews (quarterly?) +- Extract patterns, not architectures +- Document rationale for skipped changes +- Consider contributing valuable additions upstream + +### Risk 3: Name Inconsistency (Title Case vs lowercase) + +**Likelihood:** High (50+ files affected) +**Impact:** Low (cosmetic, tools handle both) +**Mitigation:** + +- Choose one convention and stick with it +- Consider following upstream lowercase convention +- Update all at once to avoid mixed state +- Document decision in style guide + +### Risk 4: Losing Your Custom Enhancements + +**Likelihood:** Low (with careful merge) +**Impact:** High (valuable custom work) +**Mitigation:** + +- Clearly mark your additions in merged files +- Add comments: `# Custom addition by jthurlburt - Phase 1.5` +- Test that both upstream improvements AND your additions work +- Keep this analysis doc as merge reference + +### Risk 5: Codex Files Creating Maintenance Burden + +**Likelihood:** Low (if skipped as recommended) +**Impact:** Low (easy to ignore) +**Mitigation:** + +- Skip `.codex/` files entirely +- Document decision to skip +- Revisit if you ever need Codex support + +## Implementation Approaches + +### Approach 1: Selective Cherry-Pick (Recommended) + +**Strategy:** Cherry-pick only valuable commits, skip Codex entirely + +```bash +# Create analysis workspace +git worktree add ../claude-settings-upstream-sync main +cd ../claude-settings-upstream-sync + +# Cherry-pick writing improvements to brainstorming +# Note: This will conflict - manual merge required +git cherry-pick e3208f1 # Writing clarity improvements + +# After manual merge, commit with clear message +git commit -m "feat(brainstorming): merge upstream proactive research pattern + +Merged from upstream commit e3208f1: +- Add Prep: Autonomous Recon phase +- Update Phase 1 to share understanding first +- Add recommendation-first pattern to Phase 2 +- Apply Strunk & White clarity improvements + +Preserved custom additions: +- Phase 1.5: Working with External References +- Phase 4.5: Challenge Your Design + +Source: obra/superpowers v3.3.1" + +# Return to main repo and merge the worktree +cd ../claude-settings +git merge claude-settings-upstream-sync/main +``` + +**Pros:** + +- Surgical precision - only what you want +- Preserves your custom work +- Clear attribution + +**Cons:** + +- Manual merge required for conflicts +- Time-intensive + +**Estimated Time:** 3-4 hours + +### Approach 2: Full Merge with Reversions (Not Recommended) + +**Strategy:** Merge everything, then revert unwanted changes + +```bash +git merge upstream/main +# Resolve conflicts +git revert +``` + +**Pros:** + +- Tracks upstream merge point +- Easier for future syncs + +**Cons:** + +- Brings in Codex files you don't need +- More complex history +- Risk of reverting too much + +**Estimated Time:** 6-8 hours + +### Approach 3: Manual Copy (Alternative) + +**Strategy:** Copy upstream brainstorming skill, manually re-add your sections + +```bash +# Save your custom sections +git show main:skills/brainstorming/SKILL.md > /tmp/current_brainstorm.md + +# Copy upstream version +git show upstream/main:skills/brainstorming/SKILL.md > skills/brainstorming/SKILL.md + +# Manually edit to add back Phase 1.5 and 4.5 from /tmp/current_brainstorm.md +# Commit +git add skills/brainstorming/SKILL.md +git commit -m "feat(brainstorming): adopt upstream improvements, preserve custom phases" +``` + +**Pros:** + +- Clean result +- Full control +- No merge complexity + +**Cons:** + +- Loses history connection to upstream +- Manual work + +**Estimated Time:** 2-3 hours + +## File Change Summary + +### Files to Modify (Tier 1) + +1. **[skills/brainstorming/SKILL.md](skills/brainstorming/SKILL.md)** - Merge upstream improvements, preserve Phase 1.5 and 4.5 +2. **[docs/upstream-analysis-2025-10-30.md](docs/upstream-analysis-2025-10-30.md)** - This analysis document + +### Files to Skip + +- **`.codex/`** - Entire directory (Codex integration not needed) +- **`RELEASE-NOTES.md`** - Upstream release notes (maintain your own CHANGELOG) +- **Plugin config changes** - You're on a different marketplace name + +### Files with Potential Future Value + +- **`README.md`** - Upstream made it more egalitarian; consider similar changes +- **Writing clarity pattern** - Consider applying to your other skills (Tier 2) + +## Detailed Merge Plan for Brainstorming Skill + +### Section-by-Section Merge Strategy + +| Section | Action | Source | Notes | +| -------------------------------- | ----------------- | -------- | --------------------------------- | +| Frontmatter | **Take upstream** | upstream | Use lowercase "brainstorming" | +| Overview | **Take upstream** | upstream | Better core principle statement | +| Quick Reference | **Take upstream** | upstream | Adds Prep phase row | +| The Process | **Take upstream** | upstream | Adds Prep checkbox | +| Prep: Autonomous Recon | **Take upstream** | upstream | New section | +| Phase 1: Understanding | **Take upstream** | upstream | Better guidance | +| Phase 1.5: External References | **Keep yours** | current | Your custom addition | +| Phase 2: Exploration | **Take upstream** | upstream | Adds recommendation-first pattern | +| Phase 3: Design Presentation | **Take upstream** | upstream | Improved guidance | +| Phase 4: Design Documentation | **Keep yours** | current | Same in both | +| Phase 4.5: Challenge Your Design | **Keep yours** | current | Your custom addition | +| Phase 5: Worktree Setup | **Keep yours** | current | Same in both | +| Phase 6: Planning Handoff | **Keep yours** | current | Same in both | +| Question Patterns | **Take upstream** | upstream | Better structure | +| When to Revisit | **Keep yours** | current | Same in both | +| Key Principles | **Take upstream** | upstream | Adds new principles | + +### Expected Line Count + +- **Current:** 224 lines +- **Upstream:** ~350 lines (estimated) +- **Merged:** ~400 lines (adds Prep phase + upstream improvements + your Phase 1.5 & 4.5) + +## Next Steps + +1. **Decide on approach** - Recommend Approach 3 (Manual Copy) for cleanest result +2. **Create worktree** - Isolate merge work +3. **Execute Tier 1** - Merge brainstorming improvements (3-4 hours) +4. **Test** - Use `/superpowers:brainstorm` to verify merged skill works +5. **Commit** - Clear commit message with attribution +6. **Document** - Note decision to skip Codex in CHANGELOG +7. **Consider Tier 2** - Writing clarity improvements to other skills (optional) + +## Conclusion + +Upstream v3.3.1 contains valuable improvements that align well with your philosophy, particularly the proactive research pattern. The recommendation is to selectively merge the brainstorming skill improvements while preserving your valuable custom additions (Phase 1.5 and 4.5). Skip the Codex integration entirely as it's not relevant to your Claude Code-focused workflow. + +**Time Investment:** 3-4 hours for Tier 1 recommendations +**Value:** Improved brainstorming skill quality with stronger research-first emphasis +**Risk:** Low - well-tested upstream changes with clear merge strategy diff --git a/hooks/hook_enforce_modern_tools.py b/hooks/hook_enforce_modern_tools.py new file mode 100755 index 000000000..5f5e03a11 --- /dev/null +++ b/hooks/hook_enforce_modern_tools.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +""" +PreToolUse hook: Enforce modern tool usage over legacy alternatives. +Denies old commands and suggests better alternatives. +""" + +import json +import re +import sys + + +# Code structure keywords that suggest ast-grep should be used +CODE_KEYWORDS = [ + r"\bclass\b", + r"\bdef\b", + r"\bfunction\b", + r"\binterface\b", + r"\bconst\b", + r"\blet\b", + r"\bvar\b", + r"\basync\b", + r"\bawait\b", + r"\bimport\b", + r"\bfrom\b", + r"\bexport\b", + r"\breturn\b", + r"\bstruct\b", + r"\benum\b", + r"\btype\b", + r"\bimpl\b", +] + +# Code file extensions +CODE_EXTENSIONS = [ + r"\.py\b", + r"\.js\b", + r"\.ts\b", + r"\.tsx\b", + r"\.jsx\b", + r"\.go\b", + r"\.rs\b", + r"\.java\b", + r"\.c\b", + r"\.cpp\b", + r"\.h\b", + r"\.hpp\b", + r"\.rb\b", + r"\.php\b", +] + + +def looks_like_code_search(command): + """Detect if grep/rg command is searching for code structures.""" + # Check for code keywords in the search pattern + for keyword in CODE_KEYWORDS: + if re.search(keyword, command, re.IGNORECASE): + return True + + # Check if searching in code files + for ext in CODE_EXTENSIONS: + if re.search(ext, command): + return True + + # Check for complex regex patterns often used in code search + if re.search(r"grep.*[\[\]{}()\|\\]", command): + return True + + return False + + +# Tool enforcement rules: (pattern, reason, check_function) +TOOL_RULES = [ + { + "pattern": r"(^|\||;|&&)\s*(grep|egrep|fgrep)\b", + "check": looks_like_code_search, + "code_reason": "Use ast-grep for searching code structures. Examples:\n ast-grep --pattern 'class $NAME' (find classes)\n ast-grep --pattern 'def $FUNC($$$)' (find function definitions)\n ast-grep --pattern 'import { $$$ } from $MOD' (find imports)", + "text_reason": "Use rg (Grep tool) for text search, ast-grep for code structures", + }, + { + "pattern": r"(^|\||;|&&)\s*find\b", + "reason": "Use fd - fd (by name), fd -p (by path), fd . (list), fd -e ", + }, + { + "pattern": r"ls\s+[^|]*-(la|R)", + "reason": "Use fd . to list files in directory", + }, + { + "pattern": r"(^|\||;|&&)\s*(sed|awk)\b", + "reason": "Use jq for JSON, yq for YAML/XML, rg for text search", + }, +] + + +def check_command(command): + """Check if command violates any tool rules.""" + for rule in TOOL_RULES: + if re.search(rule["pattern"], command): + # Check if this rule has a conditional check function + if "check" in rule and rule["check"](command): + reason = rule.get("code_reason", rule.get("reason")) + else: + reason = rule.get("text_reason", rule.get("reason")) + + return { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": reason, + } + } + return None + + +def main(): + try: + # Read hook input from stdin + hook_input = json.load(sys.stdin) + + # Extract command from Bash tool input + command = hook_input.get("tool_input", {}).get("command", "") + + if not command: + sys.exit(0) + + # Check if command violates any rules + denial = check_command(command) + + if denial: + print(json.dumps(denial)) + sys.exit(0) + + # Allow the command + sys.exit(0) + + except Exception: + # On any error, allow the command to proceed + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/hooks/hook_run_prek.py b/hooks/hook_run_prek.py new file mode 100755 index 000000000..abb607abb --- /dev/null +++ b/hooks/hook_run_prek.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +""" +PostToolUse hook: Run prek on modified files. +Runs pre-commit hooks on files that were just edited or written. +""" + +import json +import subprocess +import sys +from pathlib import Path + + +def main(): + try: + # Read hook input from stdin + hook_input = json.load(sys.stdin) + + # Check if .pre-commit-config.yaml exists + if not Path(".pre-commit-config.yaml").exists(): + sys.exit(0) + + # Extract file path from tool input + tool_input = hook_input.get("tool_input", {}) + file_path = tool_input.get("file_path") + + if not file_path: + sys.exit(0) + + # Convert to Path and check if file exists + file_path = Path(file_path) + if not file_path.exists(): + sys.exit(0) + + # Run prek on the specific file, skipping the branch check + result = subprocess.run( + ["prek", "run", "--skip", "no-commit-to-branch", "--files", str(file_path)], + capture_output=True, + text=True, + ) + + # Only report if prek failed (non-zero exit = formatting changes or errors) + if result.returncode != 0: + combined_output = result.stdout + result.stderr + output = { + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": f"Pre-commit hooks ran on {file_path}:\n\n{combined_output}", + } + } + print(json.dumps(output)) + + sys.exit(0) + + except Exception as e: + # On any error, print and fail + print(f"Hook error: {e}", file=sys.stderr) + sys.exit(2) + + +if __name__ == "__main__": + main() diff --git a/hooks/hooks.json b/hooks/hooks.json index 17e0ac87b..695992a4d 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -10,6 +10,28 @@ } ] } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/hook_enforce_modern_tools.py" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/hook_run_prek.py" + } + ] + } ] } } diff --git a/lib/initialize-skills.sh b/lib/initialize-skills.sh deleted file mode 100755 index 838671bff..000000000 --- a/lib/initialize-skills.sh +++ /dev/null @@ -1,88 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -SKILLS_DIR="${HOME}/.config/superpowers/skills" -SKILLS_REPO="https://github.com/obra/superpowers-skills.git" - -# Check if skills directory exists and is a valid git repo -if [ -d "$SKILLS_DIR/.git" ]; then - cd "$SKILLS_DIR" - - # Get the remote name for the current tracking branch - TRACKING_REMOTE=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null | cut -d'/' -f1 || echo "") - - # Fetch from tracking remote if set, otherwise try upstream then origin - if [ -n "$TRACKING_REMOTE" ]; then - git fetch "$TRACKING_REMOTE" 2>/dev/null || true - else - git fetch upstream 2>/dev/null || git fetch origin 2>/dev/null || true - fi - - # Check if we can fast-forward - LOCAL=$(git rev-parse @ 2>/dev/null || echo "") - REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "") - BASE=$(git merge-base @ @{u} 2>/dev/null || echo "") - - # Try to fast-forward merge first - if [ -n "$LOCAL" ] && [ -n "$REMOTE" ] && [ "$LOCAL" != "$REMOTE" ]; then - # Check if we can fast-forward (local is ancestor of remote) - if [ "$LOCAL" = "$BASE" ]; then - # Fast-forward merge is possible - local is behind - echo "Updating skills to latest version..." - if git merge --ff-only @{u} 2>&1; then - echo "✓ Skills updated successfully" - echo "SKILLS_UPDATED=true" - else - echo "Failed to update skills" - fi - elif [ "$REMOTE" != "$BASE" ]; then - # Remote has changes (local is behind or diverged) - echo "SKILLS_BEHIND=true" - fi - # If REMOTE = BASE, local is ahead - no action needed - fi - - exit 0 -fi - -# Skills directory doesn't exist or isn't a git repo - initialize it -echo "Initializing skills repository..." - -# Handle migration from old installation -if [ -d "${HOME}/.config/superpowers/.git" ]; then - echo "Found existing installation. Backing up..." - mv "${HOME}/.config/superpowers/.git" "${HOME}/.config/superpowers/.git.bak" - - if [ -d "${HOME}/.config/superpowers/skills" ]; then - mv "${HOME}/.config/superpowers/skills" "${HOME}/.config/superpowers/skills.bak" - echo "Your old skills are in ~/.config/superpowers/skills.bak" - fi -fi - -# Clone the skills repository -mkdir -p "${HOME}/.config/superpowers" -git clone "$SKILLS_REPO" "$SKILLS_DIR" - -cd "$SKILLS_DIR" - -# Offer to fork if gh is installed -if command -v gh &> /dev/null; then - echo "" - echo "GitHub CLI detected. Would you like to fork superpowers-skills?" - echo "Forking allows you to share skill improvements with the community." - echo "" - read -p "Fork superpowers-skills? (y/N): " -n 1 -r - echo - - if [[ $REPLY =~ ^[Yy]$ ]]; then - gh repo fork obra/superpowers-skills --remote=true - echo "Forked! You can now contribute skills back to the community." - else - git remote add upstream "$SKILLS_REPO" - fi -else - # No gh, just set up upstream remote - git remote add upstream "$SKILLS_REPO" -fi - -echo "Skills repository initialized at $SKILLS_DIR" diff --git a/scripts/inventory-repo.sh b/scripts/inventory-repo.sh new file mode 100755 index 000000000..a955f4767 --- /dev/null +++ b/scripts/inventory-repo.sh @@ -0,0 +1,69 @@ +#!/bin/bash +# Inventory a repository and list all features + +REPO_PATH="$1" +REPO_NAME=$(basename "$REPO_PATH") + +echo "# Inventory: $REPO_NAME" +echo "" +echo "**Path:** $REPO_PATH" +echo "" + +# Find skills +if [ -d "$REPO_PATH/skills" ]; then + echo "## Skills" + find "$REPO_PATH/skills" -name "SKILL.md" -o -name "*.md" | while read file; do + rel_path=${file#$REPO_PATH/} + echo "- $rel_path" + done + echo "" +fi + +# Find commands +if [ -d "$REPO_PATH/commands" ]; then + echo "## Commands" + find "$REPO_PATH/commands" -name "*.md" | while read file; do + rel_path=${file#$REPO_PATH/} + echo "- $rel_path" + done + echo "" +fi + +# Find hooks +if [ -d "$REPO_PATH/hooks" ]; then + echo "## Hooks" + find "$REPO_PATH/hooks" -name "*.md" -o -name "*.sh" | while read file; do + rel_path=${file#$REPO_PATH/} + echo "- $rel_path" + done + echo "" +fi + +# Find agents +if [ -d "$REPO_PATH/agents" ]; then + echo "## Agents" + find "$REPO_PATH/agents" -name "*.md" -o -name "*.txt" | while read file; do + rel_path=${file#$REPO_PATH/} + echo "- $rel_path" + done + echo "" +fi + +# Find scripts +if [ -d "$REPO_PATH/scripts" ]; then + echo "## Scripts" + find "$REPO_PATH/scripts" -type f | while read file; do + rel_path=${file#$REPO_PATH/} + echo "- $rel_path" + done + echo "" +fi + +# Find other directories +echo "## Other Directories" +ls -d "$REPO_PATH"/*/ 2>/dev/null | while read dir; do + dirname=$(basename "$dir") + if [[ ! "$dirname" =~ ^(skills|commands|hooks|agents|scripts|\.git)$ ]]; then + echo "- $dirname/" + fi +done diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 7a05a6710..df9c36705 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -1,5 +1,5 @@ --- -name: brainstorming +name: Brainstorming description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation --- @@ -9,89 +9,169 @@ description: Use when creating or developing anything, before writing code or im Transform rough ideas into fully-formed designs through structured questioning and alternative exploration. -**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation. +**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation. **Announce at start:** "I'm using the brainstorming skill to refine your idea into a design." ## Quick Reference -| Phase | Key Activities | Tool Usage | Output | -|-------|---------------|------------|--------| -| **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria | -| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs | -| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation | -| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ | -| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment | -| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown | +| Phase | Key Activities | Tool Usage | Output | +| ---------------------------- | --------------------------------------------- | -------------------------------------- | ------------------------------------------ | +| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm | +| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) | +| **1.5. External References** | Pattern extraction from external code/repos | Smart sampling, context mapping | Reference analysis doc (if substantial) | +| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs | +| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation | +| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ | +| **4.5. Challenge Design** | Stress-test with alternative perspectives | Steel man alternatives, bias check | Validated or revised design | +| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment | +| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown | ## The Process Copy this checklist to track progress: -``` +```text Brainstorming Progress: +- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared) - [ ] Phase 1: Understanding (purpose, constraints, criteria gathered) +- [ ] Phase 1.5: External References (if applicable - pattern extraction complete) - [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated) - [ ] Phase 3: Design Presentation (design validated in sections) - [ ] Phase 4: Design Documentation (design written to docs/plans/) +- [ ] Phase 4.5: Challenge Design (stress-tested and validated) - [ ] Phase 5: Worktree Setup (if implementing) - [ ] Phase 6: Planning Handoff (if implementing) ``` +### Prep: Autonomous Recon + +- Use existing tools (file browsing, docs, git history, tests, decisions/) to understand current project state before asking anything. +- Form your draft model: what problem you're solving, what artifacts exist, and what questions remain. +- Start the conversation by sharing that model: "Based on exploring the project state, docs, working copy, and recent commits, here's how I think this should work…" +- Ask follow-up questions only for information you cannot infer from available materials. + ### Phase 1: Understanding -- Check current project state in working directory -- Ask ONE question at a time to refine the idea -- **Use AskUserQuestion tool** when you have multiple choice options -- Gather: Purpose, constraints, success criteria -**Example using AskUserQuestion:** -``` -Question: "Where should the authentication data be stored?" -Options: - - "Session storage" (clears on tab close, more secure) - - "Local storage" (persists across sessions, more convenient) - - "Cookies" (works with SSR, compatible with older approach) +- Share your synthesized understanding first, then invite corrections or additions. +- Check `docs/decisions/` (if exists) for relevant architectural decisions + ```bash + test -d docs/decisions && fd . docs/decisions + ``` +- Ask one focused question at a time, only for gaps you cannot close yourself. +- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives. +- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner) + +**Example summary + targeted question:** + +```text +Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important? ``` +### Phase 1.5: Working with External References (when applicable) + +If your partner references external code, repos, or patterns during understanding: + +**Smart Sampling Strategy:** + +- Focus on tests (reveals behavior), core modules (shows patterns), README (architecture) +- Don't read everything - sample strategically + +**Pattern Extraction:** + +- What conventions does it follow? +- What problems does it solve? +- What design decisions did they make? + +**Context Mapping:** + +- How does their context differ from ours? +- What translates directly? +- What needs adaptation? + +**Document Insights:** + +- Create `docs/plans/--reference-analysis.md` if substantial +- Capture key learnings that inform our design + +Don't copy blindly. Understand, extract, adapt. + ### Phase 2: Exploration + - Propose 2-3 different approaches -- For each: Core architecture, trade-offs, complexity assessment -- **Use AskUserQuestion tool** to present approaches as structured choices -- Ask your human partner which approach resonates +- For each: Core architecture, trade-offs, complexity assessment, and your recommendation +- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call +- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently +- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking **Example using AskUserQuestion:** -``` + +```text Question: "Which architectural approach should we use?" Options: + - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope - "Event-driven with message queue" (scalable, complex setup, eventual consistency) - - "Direct API calls with retry logic" (simple, synchronous, easier to debug) - "Hybrid with background jobs" (balanced, moderate complexity, best of both) + +I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options. ``` ### Phase 3: Design Presentation -- Present in 200-300 word sections + +- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious - Cover: Architecture, components, data flow, error handling, testing -- Ask after each section: "Does this look right so far?" (open-ended) -- Use open-ended questions here to allow freeform feedback +- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect." +- Use open-ended questions to allow freeform feedback +- Assume ownership and proceed unless your partner redirects you ### Phase 4: Design Documentation -After design is validated, write it to a permanent document: + +After validating the design, write it to a permanent document: + - **File location:** `docs/plans/YYYY-MM-DD--design.md` (use actual date and descriptive topic) - **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality -- **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation +- **Content:** Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation - Commit the design document to git before proceeding +**If significant architectural choice was made:** + +Check if project uses ADR pattern: + +```bash +test -d docs/decisions && echo "ADR available" +``` + +If available, consider creating ADR to document the architectural decision with full context, alternatives considered, and rationale. + +### Phase 4.5: Challenge Your Design (before finalizing) + +Before exiting brainstorming, stress-test your design: + +1. **Steel man the alternatives**: What's the BEST argument for approaches you rejected? +2. **Bias check**: Are you favoring this because it's familiar? Trendy? Comfortable? +3. **Simulate perspectives**: + - **Operations**: "How do I debug this in production?" + - **Future maintainer**: "How do I modify this in 6 months?" + - **Security**: "How do I exploit this?" +4. **Test cases for the design**: Can you describe scenarios that would prove/disprove this approach? + +If you can't defend your design against these challenges, return to exploration. + ### Phase 5: Worktree Setup (for implementation) + When design is approved and implementation will follow: + - Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace." - **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees - Follow that skill's process for directory selection, safety verification, and setup - Return here when worktree ready ### Phase 6: Planning Handoff + Ask: "Ready to create the implementation plan?" When your human partner confirms (any affirmative response): + - Announce: "I'm using the writing-plans skill to create the implementation plan." - **REQUIRED SUB-SKILL:** Use superpowers:writing-plans - Create detailed plan in the worktree @@ -100,26 +180,31 @@ When your human partner confirms (any affirmative response): ### When to Use AskUserQuestion Tool -**Use AskUserQuestion for:** -- Phase 1: Clarifying questions with 2-4 clear options -- Phase 2: Architectural approach selection (2-3 alternatives) -- Any decision with distinct, mutually exclusive choices -- When options have clear trade-offs to explain +**Use AskUserQuestion when:** + +- You need your partner to make a judgement call among real alternatives +- You have a recommendation and can explain why it’s your preference +- Prioritization is ambiguous and cannot be inferred from existing materials -**Benefits:** -- Structured presentation of options with descriptions -- Clear trade-off visibility for partner -- Forces explicit choice (prevents vague "maybe both" responses) +**Best practices:** + +- State your preferred option and rationale inside the question so your partner can agree or redirect +- If you know the answer from repo/docs, state it as fact and proceed—no question needed +- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner ### When to Use Open-Ended Questions **Use open-ended questions for:** + - Phase 3: Design validation ("Does this look right so far?") - When you need detailed feedback or explanation - When partner should describe their own requirements - When structured options would limit creative input +Frame them to confirm or expand your current understanding rather than reopening settled topics. + **Example decision flow:** + - "What authentication method?" → Use AskUserQuestion (2-4 options) - "Does this design handle your use case?" → Open-ended (validation) @@ -145,21 +230,23 @@ digraph revisit_phases { ``` **You can and should go backward when:** + - Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1 - Validation shows fundamental gap in requirements → Return to Phase 1 - Partner questions approach during Phase 3 → Return to Phase 2 - Something doesn't make sense → Go back and clarify -**Don't force forward linearly** when going backward would give better results. +**Avoid forcing forward linearly** when going backward would give better results. ## Key Principles -| Principle | Application | -|-----------|-------------| -| **One question at a time** | Phase 1: Single question per message, use AskUserQuestion for choices | -| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs | -| **YAGNI ruthlessly** | Remove unnecessary features from all designs | -| **Explore alternatives** | Always propose 2-3 approaches before settling | -| **Incremental validation** | Present design in sections, validate each | -| **Flexible progression** | Go backward when needed - flexibility > rigidity | -| **Announce usage** | State skill usage at start of session | +| Principle | Application | +| -------------------------- | ---------------------------------------------------------------------------------------------- | +| **One question at a time** | Phase 1: Single targeted question only for gaps you can’t close yourself | +| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs | +| **YAGNI ruthlessly** | Remove unnecessary features from all designs | +| **Explore alternatives** | Always propose 2-3 approaches before settling | +| **Incremental validation** | Present design in sections, validate each | +| **Flexible progression** | Go backward when needed - flexibility > rigidity | +| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict | +| **Announce usage** | State skill usage at start of session | diff --git a/skills/code-and-project-cleanup/SKILL.md b/skills/code-and-project-cleanup/SKILL.md new file mode 100644 index 000000000..2cf738728 --- /dev/null +++ b/skills/code-and-project-cleanup/SKILL.md @@ -0,0 +1,123 @@ +--- +name: Code and Project Cleanup +description: Use before commits or when project feels cluttered - safely removes unnecessary comments, debug statements, temp files, and build artifacts with git checkpoints +--- + +# Code and Project Cleanup + +## Overview + +Systematically clean code and project artifacts while preserving valuable work. Remove unnecessary comments and debug statements, clean temporary files and build artifacts, all with git safety checkpoints for easy rollback. + +## When to Use + +- Before commits +- After development sessions +- During refactoring +- When project feels cluttered +- Before code reviews + +## Core Safety Principles + +**Always create git checkpoint first** for easy rollback: + +```bash +git add -A && git commit -m "Pre-cleanup checkpoint" || echo "No changes to commit" +``` + +**Protected directories** (never touch): + +- `.claude/`, `.git/` - Configuration and version control +- `node_modules/`, `vendor/` - Dependencies +- `.env`, `.env.*` - Environment configuration + +**Verification before action**: Show what will be removed and why, then get confirmation + +## Comment Cleanup + +Use Glob to find source files, Read to examine patterns, Grep to locate specific types. + +**Remove (WHAT comments):** + +- Restate what code does +- State the obvious ("constructor" above a constructor) +- Add no value beyond code itself +- Explain self-evident syntax + +**Preserve (WHY comments):** + +- Explain WHY something is done (business logic, design decisions) +- Document complex algorithms or non-obvious behavior +- Contain TODOs, FIXMEs, HACKs tracking technical debt +- Reference bug tickets or external documentation +- Warn about edge cases or unusual requirements + +**Example:** + +```python +# ❌ Remove: "Initialize variable to store count" +count = 0 + +# ✅ Keep: "Start at 0 to exclude header row in CSV parsing" +count = 0 +``` + +## Debug Statement Cleanup + +**Remove:** + +- Console.log, print(), System.out.println() for debugging +- Commented-out code blocks from debug sessions +- Temporary timing or profiling code +- Hard-coded test values in production code + +**Preserve:** + +- Production monitoring and logging +- Error handling and exception logging +- Audit trail or compliance logging + +## Project Artifact Cleanup + +### Common Temporary Patterns + +Use Glob with these patterns: + +- `*.log`, `*.tmp`, `*~` - Logs, temp files, backups +- `*.swp`, `*.swo` - Editor swap files +- `.DS_Store`, `Thumbs.db` - OS metadata + +### Build Artifact Patterns + +- `dist/`, `build/`, `target/` - Build output directories +- `*.o`, `*.pyc`, `*.class` - Compiled files +- `__pycache__/` - Python bytecode cache + +### Deletion Process + +1. Create git checkpoint, identify with Glob/Read, check file age (>7 days safer) +2. Verify git status (untracked safer), group similar files +3. Show removal plan with patterns and reasons, get confirmation +4. Create TodoWrite list, delete, verify integrity (tests/build) + +## Red Flags and Pitfalls + +**Stop and ask:** + +- Unrecognized patterns, files modified <24h, large directories +- Files in README, protected directories, or potential config files + +**Verify before removal:** + +- `.cache` (performance), `.tmp` (session data), commented code (examples) +- File contents (Read), git status (tracked = important), file age, build dependencies + +## Rollback + +If cleanup causes issues: + +```bash +git reset --hard HEAD~1 # Restore from checkpoint +``` + +Every cleanup is reversible through git checkpoint, maintaining project safety. diff --git a/skills/collision-zone-thinking/SKILL.md b/skills/collision-zone-thinking/SKILL.md new file mode 100644 index 000000000..6e950bbb6 --- /dev/null +++ b/skills/collision-zone-thinking/SKILL.md @@ -0,0 +1,63 @@ +--- +name: Collision-Zone Thinking +description: Force unrelated concepts together to discover emergent properties - "What if we treated X like Y?" +when_to_use: when conventional approaches feel inadequate and you need breakthrough innovation by forcing unrelated concepts together +version: 1.1.0 +--- + +# Collision-Zone Thinking + +## Overview + +Revolutionary insights come from forcing unrelated concepts to collide. Treat X like Y and see what emerges. + +**Core principle:** Deliberate metaphor-mixing generates novel solutions. + +## Quick Reference + +| Stuck On | Try Treating As | Might Discover | +| -------------------- | ---------------- | ----------------------------------------- | +| Code organization | DNA/genetics | Mutation testing, evolutionary algorithms | +| Service architecture | Lego bricks | Composable microservices, plug-and-play | +| Data management | Water flow | Streaming, data lakes, flow-based systems | +| Request handling | Postal mail | Message queues, async processing | +| Error handling | Circuit breakers | Fault isolation, graceful degradation | + +## Process + +1. **Pick two unrelated concepts** from different domains +2. **Force combination**: "What if we treated [A] like [B]?" +3. **Explore emergent properties**: What new capabilities appear? +4. **Test boundaries**: Where does the metaphor break? +5. **Extract insight**: What did we learn? + +## Example Collision + +**Problem:** Complex distributed system with cascading failures + +**Collision:** "What if we treated services like electrical circuits?" + +**Emergent properties:** + +- Circuit breakers (disconnect on overload) +- Fuses (one-time failure protection) +- Ground faults (error isolation) +- Load balancing (current distribution) + +**Where it works:** Preventing cascade failures +**Where it breaks:** Circuits don't have retry logic +**Insight gained:** Failure isolation patterns from electrical engineering + +## Red Flags You Need This + +- "I've tried everything in this domain" +- Solutions feel incremental, not breakthrough +- Stuck in conventional thinking +- Need innovation, not optimization + +## Remember + +- Wild combinations often yield best insights +- Test metaphor boundaries rigorously +- Document even failed collisions (they teach) +- Best source domains: physics, biology, economics, psychology diff --git a/skills/condition-based-waiting/SKILL.md b/skills/condition-based-waiting/SKILL.md index 1684a5741..af34461d6 100644 --- a/skills/condition-based-waiting/SKILL.md +++ b/skills/condition-based-waiting/SKILL.md @@ -1,5 +1,5 @@ --- -name: condition-based-waiting +name: Condition-Based Waiting description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses --- @@ -27,12 +27,14 @@ digraph when_to_use { ``` **Use when:** + - Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`) - Tests are flaky (pass sometimes, fail under load) - Tests timeout when run in parallel - Waiting for async operations to complete **Don't use when:** + - Testing actual timing behavior (debounce, throttle intervals) - Always document WHY if using arbitrary timeout @@ -40,7 +42,7 @@ digraph when_to_use { ```typescript // ❌ BEFORE: Guessing at timing -await new Promise(r => setTimeout(r, 50)); +await new Promise((r) => setTimeout(r, 50)); const result = getResult(); expect(result).toBeDefined(); @@ -52,22 +54,23 @@ expect(result).toBeDefined(); ## Quick Patterns -| Scenario | Pattern | -|----------|---------| -| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` | -| Wait for state | `waitFor(() => machine.state === 'ready')` | -| Wait for count | `waitFor(() => items.length >= 5)` | -| Wait for file | `waitFor(() => fs.existsSync(path))` | -| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` | +| Scenario | Pattern | +| ----------------- | ---------------------------------------------------- | +| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` | +| Wait for state | `waitFor(() => machine.state === 'ready')` | +| Wait for count | `waitFor(() => items.length >= 5)` | +| Wait for file | `waitFor(() => fs.existsSync(path))` | +| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` | ## Implementation Generic polling function: + ```typescript async function waitFor( condition: () => T | undefined | null | false, description: string, - timeoutMs = 5000 + timeoutMs = 5000, ): Promise { const startTime = Date.now(); @@ -76,10 +79,12 @@ async function waitFor( if (result) return result; if (Date.now() - startTime > timeoutMs) { - throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`); + throw new Error( + `Timeout waiting for ${description} after ${timeoutMs}ms`, + ); } - await new Promise(r => setTimeout(r, 10)); // Poll every 10ms + await new Promise((r) => setTimeout(r, 10)); // Poll every 10ms } } ``` @@ -101,12 +106,13 @@ See @example.ts for complete implementation with domain-specific helpers (`waitF ```typescript // Tool ticks every 100ms - need 2 ticks to verify partial output -await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition -await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior +await waitForEvent(manager, "TOOL_STARTED"); // First: wait for condition +await new Promise((r) => setTimeout(r, 200)); // Then: wait for timed behavior // 200ms = 2 ticks at 100ms intervals - documented and justified ``` **Requirements:** + 1. First wait for triggering condition 2. Based on known timing (not guessing) 3. Comment explaining WHY @@ -114,6 +120,7 @@ await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior ## Real-World Impact From debugging session (2025-10-03): + - Fixed 15 flaky tests across 3 files - Pass rate: 60% → 100% - Execution time: 40% faster diff --git a/skills/condition-based-waiting/example.ts b/skills/condition-based-waiting/example.ts index 703a06b65..a9522120b 100644 --- a/skills/condition-based-waiting/example.ts +++ b/skills/condition-based-waiting/example.ts @@ -2,8 +2,8 @@ // From: Lace test infrastructure improvements (2025-10-03) // Context: Fixed 15 flaky tests by replacing arbitrary timeouts -import type { ThreadManager } from '~/threads/thread-manager'; -import type { LaceEvent, LaceEventType } from '~/threads/types'; +import type { ThreadManager } from "~/threads/thread-manager"; +import type { LaceEvent, LaceEventType } from "~/threads/types"; /** * Wait for a specific event type to appear in thread @@ -21,7 +21,7 @@ export function waitForEvent( threadManager: ThreadManager, threadId: string, eventType: LaceEventType, - timeoutMs = 5000 + timeoutMs = 5000, ): Promise { return new Promise((resolve, reject) => { const startTime = Date.now(); @@ -33,7 +33,11 @@ export function waitForEvent( if (event) { resolve(event); } else if (Date.now() - startTime > timeoutMs) { - reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`)); + reject( + new Error( + `Timeout waiting for ${eventType} event after ${timeoutMs}ms`, + ), + ); } else { setTimeout(check, 10); // Poll every 10ms for efficiency } @@ -62,7 +66,7 @@ export function waitForEventCount( threadId: string, eventType: LaceEventType, count: number, - timeoutMs = 5000 + timeoutMs = 5000, ): Promise { return new Promise((resolve, reject) => { const startTime = Date.now(); @@ -76,8 +80,8 @@ export function waitForEventCount( } else if (Date.now() - startTime > timeoutMs) { reject( new Error( - `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})` - ) + `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`, + ), ); } else { setTimeout(check, 10); @@ -113,7 +117,7 @@ export function waitForEventMatch( threadId: string, predicate: (event: LaceEvent) => boolean, description: string, - timeoutMs = 5000 + timeoutMs = 5000, ): Promise { return new Promise((resolve, reject) => { const startTime = Date.now(); @@ -125,7 +129,9 @@ export function waitForEventMatch( if (event) { resolve(event); } else if (Date.now() - startTime > timeoutMs) { - reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`)); + reject( + new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`), + ); } else { setTimeout(check, 10); } diff --git a/skills/defense-in-depth/SKILL.md b/skills/defense-in-depth/SKILL.md index 08d69930b..c62b677c4 100644 --- a/skills/defense-in-depth/SKILL.md +++ b/skills/defense-in-depth/SKILL.md @@ -1,5 +1,5 @@ --- -name: defense-in-depth +name: Defense-in-Depth Validation description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible --- @@ -17,6 +17,7 @@ Single validation: "We fixed the bug" Multiple layers: "We made the bug impossible" Different layers catch different cases: + - Entry validation catches most bugs - Business logic catches edge cases - Environment guards prevent context-specific dangers @@ -25,12 +26,13 @@ Different layers catch different cases: ## The Four Layers ### Layer 1: Entry Point Validation + **Purpose:** Reject obviously invalid input at API boundary ```typescript function createProject(name: string, workingDirectory: string) { - if (!workingDirectory || workingDirectory.trim() === '') { - throw new Error('workingDirectory cannot be empty'); + if (!workingDirectory || workingDirectory.trim() === "") { + throw new Error("workingDirectory cannot be empty"); } if (!existsSync(workingDirectory)) { throw new Error(`workingDirectory does not exist: ${workingDirectory}`); @@ -43,30 +45,32 @@ function createProject(name: string, workingDirectory: string) { ``` ### Layer 2: Business Logic Validation + **Purpose:** Ensure data makes sense for this operation ```typescript function initializeWorkspace(projectDir: string, sessionId: string) { if (!projectDir) { - throw new Error('projectDir required for workspace initialization'); + throw new Error("projectDir required for workspace initialization"); } // ... proceed } ``` ### Layer 3: Environment Guards + **Purpose:** Prevent dangerous operations in specific contexts ```typescript async function gitInit(directory: string) { // In tests, refuse git init outside temp directories - if (process.env.NODE_ENV === 'test') { + if (process.env.NODE_ENV === "test") { const normalized = normalize(resolve(directory)); const tmpDir = normalize(resolve(tmpdir())); if (!normalized.startsWith(tmpDir)) { throw new Error( - `Refusing git init outside temp dir during tests: ${directory}` + `Refusing git init outside temp dir during tests: ${directory}`, ); } } @@ -75,12 +79,13 @@ async function gitInit(directory: string) { ``` ### Layer 4: Debug Instrumentation + **Purpose:** Capture context for forensics ```typescript async function gitInit(directory: string) { const stack = new Error().stack; - logger.debug('About to git init', { + logger.debug("About to git init", { directory, cwd: process.cwd(), stack, @@ -103,12 +108,14 @@ When you find a bug: Bug: Empty `projectDir` caused `git init` in source code **Data flow:** + 1. Test setup → empty string 2. `Project.create(name, '')` 3. `WorkspaceManager.createWorkspace('')` 4. `git init` runs in `process.cwd()` **Four layers added:** + - Layer 1: `Project.create()` validates not empty/exists/writable - Layer 2: `WorkspaceManager` validates projectDir not empty - Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests @@ -119,6 +126,7 @@ Bug: Empty `projectDir` caused `git init` in source code ## Key Insight All four layers were necessary. During testing, each layer caught bugs the others missed: + - Different code paths bypassed entry validation - Mocks bypassed business logic checks - Edge cases on different platforms needed environment guards diff --git a/skills/dispatching-parallel-agents/SKILL.md b/skills/dispatching-parallel-agents/SKILL.md index 493dea2db..20de86c2f 100644 --- a/skills/dispatching-parallel-agents/SKILL.md +++ b/skills/dispatching-parallel-agents/SKILL.md @@ -1,30 +1,32 @@ --- -name: dispatching-parallel-agents -description: Use when facing 3+ independent failures that can be investigated without shared state or dependencies - dispatches multiple Claude agents to investigate and fix independent problems concurrently +name: Dispatching Parallel Agents +description: Use when facing 3+ independent tasks (debugging failures, analyzing codebases, researching domains) that can be handled without shared state or dependencies - dispatches multiple Claude agents to work concurrently on separate problem domains --- # Dispatching Parallel Agents ## Overview -When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel. +When you have multiple unrelated tasks (debugging failures, analyzing codebases, researching patterns), working on them sequentially wastes time. Each task is independent and can happen in parallel. -**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently. +**Core principle:** Dispatch one agent per independent domain. Let them work concurrently. + +**Use for:** Debugging, research, analysis, or any independent tasks. ## When to Use ```dot digraph when_to_use { - "Multiple failures?" [shape=diamond]; + "Multiple tasks?" [shape=diamond]; "Are they independent?" [shape=diamond]; - "Single agent investigates all" [shape=box]; - "One agent per problem domain" [shape=box]; + "Single agent handles all" [shape=box]; + "One agent per domain" [shape=box]; "Can they work in parallel?" [shape=diamond]; "Sequential agents" [shape=box]; "Parallel dispatch" [shape=box]; - "Multiple failures?" -> "Are they independent?" [label="yes"]; - "Are they independent?" -> "Single agent investigates all" [label="no - related"]; + "Multiple tasks?" -> "Are they independent?" [label="yes (3+)"]; + "Are they independent?" -> "Single agent handles all" [label="no - related"]; "Are they independent?" -> "Can they work in parallel?" [label="yes"]; "Can they work in parallel?" -> "Parallel dispatch" [label="yes"]; "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"]; @@ -32,21 +34,26 @@ digraph when_to_use { ``` **Use when:** -- 3+ test files failing with different root causes -- Multiple subsystems broken independently -- Each problem can be understood without context from others -- No shared state between investigations + +- **Debugging:** 3+ test files failing with different root causes +- **Research:** Analyzing multiple independent codebases/frameworks +- **Analysis:** Investigating separate problem domains +- Each task can be understood without context from others +- No shared state between tasks **Don't use when:** -- Failures are related (fix one might fix others) + +- Tasks are related (one informs the other) - Need to understand full system state - Agents would interfere with each other +- Tasks require sequential execution ## The Pattern ### 1. Identify Independent Domains Group failures by what's broken: + - File A tests: Tool approval flow - File B tests: Batch completion behavior - File C tests: Abort functionality @@ -56,6 +63,7 @@ Each domain is independent - fixing tool approval doesn't affect abort tests. ### 2. Create Focused Agent Tasks Each agent gets: + - **Specific scope:** One test file or subsystem - **Clear goal:** Make these tests pass - **Constraints:** Don't change other code @@ -65,15 +73,16 @@ Each agent gets: ```typescript // In Claude Code / AI environment -Task("Fix agent-tool-abort.test.ts failures") -Task("Fix batch-completion-behavior.test.ts failures") -Task("Fix tool-approval-race-conditions.test.ts failures") +Task("Fix agent-tool-abort.test.ts failures"); +Task("Fix batch-completion-behavior.test.ts failures"); +Task("Fix tool-approval-race-conditions.test.ts failures"); // All three run concurrently ``` ### 4. Review and Integrate When agents return: + - Read each summary - Verify fixes don't conflict - Run full test suite @@ -82,6 +91,7 @@ When agents return: ## Agent Prompt Structure Good agent prompts are: + 1. **Focused** - One clear problem domain 2. **Self-contained** - All context needed to understand the problem 3. **Specific about output** - What should the agent return? @@ -123,16 +133,20 @@ Return: Summary of what you found and what you fixed. ## When NOT to Use -**Related failures:** Fixing one might fix others - investigate together first -**Need full context:** Understanding requires seeing entire system -**Exploratory debugging:** You don't know what's broken yet -**Shared state:** Agents would interfere (editing same files, using same resources) +**Related tasks:** One task informs the other - work sequentially +**Need full context:** Understanding requires seeing entire system together +**Exploratory work:** You don't know what domains exist yet +**Shared state:** Agents would interfere (editing same files, conflicting changes) +**Sequential dependencies:** Task B requires results from Task A + +## Real Examples -## Real Example from Session +### Example 1: Debugging (2025-10-03) **Scenario:** 6 test failures across 3 files after major refactoring **Failures:** + - agent-tool-abort.test.ts: 3 failures (timing issues) - batch-completion-behavior.test.ts: 2 failures (tools not executing) - tool-approval-race-conditions.test.ts: 1 failure (execution count = 0) @@ -140,6 +154,7 @@ Return: Summary of what you found and what you fixed. **Decision:** Independent domains - abort logic separate from batch completion separate from race conditions **Dispatch:** + ``` Agent 1 → Fix agent-tool-abort.test.ts Agent 2 → Fix batch-completion-behavior.test.ts @@ -147,6 +162,7 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts ``` **Results:** + - Agent 1: Replaced timeouts with event-based waiting - Agent 2: Fixed event structure bug (threadId in wrong place) - Agent 3: Added wait for async tool execution to complete @@ -155,6 +171,42 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts **Time saved:** 3 problems solved in parallel vs sequentially +### Example 2: Research (2025-10-23) + +**Scenario:** Analyze 3 independent technology domains for pattern extraction + +**Domains:** + +- Domain 1: pytest testing framework patterns +- Domain 2: webpack/vite build tool patterns +- Domain 3: Terraform infrastructure patterns + +**Decision:** Independent research - testing frameworks unrelated to build tools unrelated to IaC + +**Dispatch:** + +```typescript +Task( + "Analyze pytest patterns - best practices, anti-patterns, conventions. Return JSON.", +); +Task( + "Analyze webpack/vite patterns - config patterns, optimizations. Return JSON.", +); +Task( + "Analyze Terraform patterns - module structure, state management, security. Return JSON.", +); +``` + +**Results:** + +- Agent 1: pytest best practices with fixture patterns +- Agent 2: webpack vs vite architectural differences +- Agent 3: Terraform module structure patterns + +**Integration:** All analysis independent, combined into comprehensive report + +**Time saved:** 3 domains analyzed in ~3 minutes vs 9+ minutes sequentially + ## Key Benefits 1. **Parallelization** - Multiple investigations happen simultaneously @@ -165,6 +217,7 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts ## Verification After agents return: + 1. **Review each summary** - Understand what changed 2. **Check for conflicts** - Did agents edit same code? 3. **Run full suite** - Verify all fixes work together @@ -172,9 +225,20 @@ After agents return: ## Real-World Impact -From debugging session (2025-10-03): -- 6 failures across 3 files -- 3 agents dispatched in parallel +**Debugging session** (2025-10-03): + +- 6 failures across 3 files → 3 agents dispatched - All investigations completed concurrently -- All fixes integrated successfully -- Zero conflicts between agent changes +- All fixes integrated successfully, zero conflicts + +**Research session** (2025-10-23): + +- 3 technology domains → 3 agents dispatched +- Completed in ~3 minutes vs 9+ sequentially +- Structured JSON from all agents, combined into analysis + +**Bake-off validation** (2025-10-23): + +- Task tool approach: 100% success rate, 3-minute completion +- Simple one-line dispatch per agent +- Reliable across debugging and research use cases diff --git a/skills/documentation-management/SKILL.md b/skills/documentation-management/SKILL.md new file mode 100644 index 000000000..e739c62c1 --- /dev/null +++ b/skills/documentation-management/SKILL.md @@ -0,0 +1,94 @@ +--- +name: Documentation Management +description: Use when documentation is outdated after code changes - systematically updates README, CHANGELOG, API docs, and guides based on actual implementation changes +--- + +# Documentation Management + +## Overview + +Systematically update project documentation to match code reality. Analyze changes, identify affected documentation, and update all relevant files maintaining consistency across README, CHANGELOG, API docs, and guides. + +## When to Use + +- After implementing features +- After fixing bugs +- After refactoring or architecture changes +- When documentation is outdated across multiple files +- Before creating pull requests + +## Core Approach + +**Analyze changes → Identify affected docs → Update systematically → Verify consistency** + +1. **Understand scope**: Analyze code changes from conversation or codebase comparison +2. **Read all docs**: Use Glob to find markdown files, Read each documentation file completely +3. **Identify gaps**: Compare implementation vs documentation (new features, changed APIs, removed functionality) +4. **Update comprehensively**: Modify all affected docs, not just README + +## Documentation Modes + +**Overview mode** (when starting): Glob markdown files, read each, present summary with gaps + +**Sync mode** (during work): Update docs incrementally, CHANGELOG with changes, README for features + +**Session mode** (after coding): Review conversation, group by type (Added, Fixed, Changed), update all affected docs + +## Update Patterns by Change Type + +| Change Type | Documentation Updates | +| ----------------------- | ----------------------------------------------------------------------- | +| **New feature** | README features, CHANGELOG (minor bump), API docs, usage examples | +| **Bug fix** | CHANGELOG (patch bump), troubleshooting if significant | +| **Refactoring** | Architecture docs, migration guide if breaking, CHANGELOG | +| **Architecture change** | README architecture section, CHANGELOG, ADR in decisions/ (if exists) | +| **Security fix** | Security policy, CHANGELOG with Security section, README if user-facing | +| **Performance** | Benchmarks, CHANGELOG with improved metrics, optimization guides | +| **Breaking change** | CHANGELOG (major bump), migration guide, README with upgrade path | + +## CHANGELOG Version Guidance + +Suggest version bumps following semver: + +- **MAJOR**: Breaking changes, API removals, incompatible modifications +- **MINOR**: New features, enhancements, deprecations (backward compatible) +- **PATCH**: Bug fixes, documentation updates, internal changes + +Format follows [Keep a Changelog](https://keepachangelog.com/): + +- Group by type: Added, Changed, Deprecated, Removed, Fixed, Security +- Newest entries at top +- Link to issues/PRs when available + +## Essential Rules + +**ALWAYS:** + +- Read existing docs completely before updates +- Find exact section needing update, modify in-place +- Preserve custom content and existing formatting +- Match project's documentation style and conventions +- Update all affected files, not just one +- Include inline source links for factual claims: `[claim](https://source.url)`. Unverified claims are unverifiable + +**AVOID:** + +- Deleting existing documentation +- Overwriting custom sections (respect `` markers) +- Changing documentation style drastically +- Adding AI attribution or Claude Code markers +- Creating unnecessary new documentation files + +## Documentation Types + +- **README**: Features, setup, usage, architecture +- **CHANGELOG**: Version history with categorized changes +- **API docs**: Endpoints, parameters, responses +- **Configuration**: Environment variables, settings +- **Guides**: Architecture, deployment, troubleshooting, migration +- **ADR** (decisions/): Architecture decisions with rationale (if `docs/decisions/` exists) +- **DISCOVERIES** (discoveries/): Known issues and solutions (if `docs/discoveries/DISCOVERIES.md` exists) + +## Completion + +Ask how to proceed: update all, focus on specific files, create missing docs, or generate migration guide. diff --git a/skills/enhancing-superpowers/SKILL.md b/skills/enhancing-superpowers/SKILL.md new file mode 100644 index 000000000..de436d997 --- /dev/null +++ b/skills/enhancing-superpowers/SKILL.md @@ -0,0 +1,426 @@ +--- +name: Enhancing Superpowers +description: Use when adding external concepts to this superpowers/claude-settings project - requires checking existing 33 skills first, using worktrees for exploration, following SKILL.md conventions, and ensuring philosophy alignment before integration +--- + +# Enhancing Superpowers + +## Overview + +Project-specific guide for integrating external concepts into the superpowers/claude-settings skills library. + +**Core principle:** Enhance existing skills before creating new ones. Extract patterns, not architectures. + +**Announce at start:** "I'm using the enhancing-superpowers skill to integrate this concept properly." + +## When to Use + +Use when: + +- Analyzing external projects for superpowers enhancements +- User says "add pattern X from project Y" +- Considering new capabilities for skills library +- Evaluating whether concept fits superpowers philosophy + +Skip when: + +- Making simple typo fixes +- Updating documentation only +- Changes don't involve external concepts + +## Critical First Steps + +### Step 1: Check Existing Skills (MANDATORY) + +**Before proposing anything new, check if already covered:** + +```bash +# List all 33+ existing skills +ls skills/ + +# Search for related concepts +grep -r "keyword" skills/*/SKILL.md + +# Check specific skills that might already cover it: +# - test-driven-development (TDD workflows) +# - systematic-debugging (debugging approaches) +# - brainstorming (design processes) +# - writing-plans / executing-plans (planning workflows) +# - using-git-worktrees (isolated workspaces) +# - documentation-management (docs approaches) +# And 27+ others... +``` + +**Common mistake:** Creating new skill when existing skill just needs enhancement. + +### Step 2: Decision Tree + +``` +Found in existing skill? +├─ YES → Enhance existing skill (update SKILL.md) +│ └─ Test with subagents per writing-skills +└─ NO → New concept? + ├─ Fits skills philosophy? (auto-activate, TDD, systematic) + │ ├─ YES → Create new skill + │ │ └─ Follow writing-skills skill (TDD approach) + │ └─ NO → Consider different approach + │ ├─ Infrastructure? → Add to .claude/tools/ + │ ├─ Documentation? → Add to docs/ + │ ├─ Convention? → Update CLAUDE.md + │ └─ Philosophy? → Create philosophy doc + └─ Already have 33+ skills? + └─ High bar for new skills (avoid proliferation) +``` + +### Step 3: Use Worktrees (REQUIRED) + +**ALWAYS use worktrees for exploration:** + +```bash +# Follow using-git-worktrees skill +# 1. Check for .worktrees/ directory +ls -la .worktrees/ + +# 2. Verify .gitignore +grep "^\.worktrees/$" .gitignore + +# 3. Create worktree +git worktree add .worktrees/amplifier-integration -b feature/amplifier-integration + +# 4. Work in isolation +cd .worktrees/amplifier-integration +``` + +**Why:** Prevents polluting main branch during exploration. + +**REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees for complete workflow. + +## Superpowers Project Structure + +**Know where things go:** + +``` +claude-settings/ +├── skills/ # 33+ skills, auto-activate +│ ├── skill-name/ +│ │ └── SKILL.md # Main skill file +│ └── ... +├── .claude/ +│ ├── commands/ # Slash commands +│ ├── tools/ # Hooks and utilities +│ └── settings.json # Project config +├── docs/ # Documentation +├── CLAUDE.md # Project conventions +├── CHANGELOG.md # Change history +└── README.md # User-facing docs +``` + +**File naming conventions:** + +- Skills: lowercase-with-hyphens +- Commands: lowercase-with-hyphens.md +- Tools: snake_case.py or kebab-case.sh +- Docs: UPPERCASE.md or lowercase.md + +## Integration Approaches by Type + +### Type 1: Knowledge Management Pattern + +**Example:** DISCOVERIES.md, decision tracking + +**Approach:** + +1. Create template/documentation +2. Integrate with existing skills (reference from systematic-debugging, when-stuck) +3. Add to SessionStart reminder if needed + +**Avoid:** Creating new skill just for using a template + +### Type 2: Workflow Pattern + +**Example:** Artifact-driven phases, approval gates + +**Approach:** + +1. Check existing workflow skills (writing-plans, executing-plans) +2. Enhance those skills with new patterns +3. Test integration with existing workflows + +**Avoid:** Creating parallel workflow system + +### Type 3: Infrastructure + +**Example:** Hooks, transcript system, status line + +**Approach:** + +1. Add to .claude/tools/ +2. Update .claude/settings.json if hooks +3. Create slash command if user-facing +4. Document in README.md + +**Avoid:** Putting infrastructure in skills/ + +### Type 4: New Skill (High Bar) + +**Example:** New capability not covered by 33 existing skills + +**Approach:** + +1. **REQUIRED:** Follow superpowers:writing-skills (TDD for skills) +2. Run baseline tests WITHOUT skill +3. Write minimal skill addressing baseline failures +4. Test WITH skill until bulletproof +5. Deploy with confidence + +**Criteria for new skill:** + +- Not covered by existing 33+ skills +- Broadly applicable (not project-specific) +- Auto-activatable (clear triggering conditions) +- Follows TDD/systematic philosophy +- Worth maintaining long-term + +### Type 5: Philosophy/Principles + +**Example:** Implementation philosophy, modular design principles + +**Approach:** + +1. Create docs/ file +2. Reference from relevant skills +3. Add to SessionStart context if foundational + +**Avoid:** Creating skill for every principle + +### Type 6: Decision Documentation + +**Example:** Deciding to add/reject external patterns + +**Approach:** + +1. Check if project uses ADR pattern: + ```bash + test -d docs/decisions && echo "ADR available" + ``` +2. **If exists**: Create ADR documenting integration decision with context, rationale, alternatives +3. **Otherwise**: Use `mem add "Integration decision: [what] because [why]. Alternatives: [rejected options]" --tags "decision,integration"` +4. Reference in related skills or documentation + +**Avoid:** Making major decisions without documenting rationale + +## Philosophy Alignment Checklist + +**Superpowers values:** + +- ✅ Test-Driven Development (write tests first, always) +- ✅ Systematic over ad-hoc (process over guessing) +- ✅ Complexity reduction (simplicity as primary goal) +- ✅ Evidence over claims (verify before declaring success) +- ✅ Auto-activation (skills activate automatically when relevant) +- ✅ Integrated workflows (skills work together seamlessly) + +**Before integrating, ask:** + +- [ ] Does this align with TDD philosophy? +- [ ] Does this make things simpler or more complex? +- [ ] Can this auto-activate or requires explicit invocation? +- [ ] Does this integrate with existing skills or create parallel system? +- [ ] Will users adopt this or is it too heavyweight? +- [ ] Does this solve a real problem we've experienced? + +**Red flags:** + +- ❌ Requires explicit invocation (conflicts with auto-activation) +- ❌ Adds significant complexity +- ❌ Creates parallel system to existing skills +- ❌ Heavyweight workflow for simple tasks +- ❌ Speculative feature (no proven need) + +## SKILL.md Format Requirements + +**When creating/editing skills, follow exact format:** + +```markdown +--- +name: Skill-Name-With-Hyphens +description: Use when [triggering conditions] - [what it does, third person, under 500 chars] +--- + +# Skill Name + +## Overview + +Core principle in 1-2 sentences. + +## When to Use + +Bullet list with symptoms and use cases +When NOT to use + +## Core Pattern + +Before/after comparison + +## Quick Reference + +Table for common operations + +## Common Mistakes + +What goes wrong + fixes + +## Integration + +Which skills this pairs with +``` + +**Frontmatter rules:** + +- Only `name` and `description` fields (max 1024 chars total) +- name: letters, numbers, hyphens only (no parens, special chars) +- description: Start with "Use when...", third person, specific triggers + +**CSO (Claude Search Optimization):** + +- Use concrete triggers not abstractions +- Include error messages, symptoms, tool names +- Technology-agnostic unless skill is tech-specific + +**REQUIRED SUB-SKILL:** Use superpowers:writing-skills for complete format guide. + +## Testing Requirements + +**For new/modified skills:** + +1. **RED Phase:** Run baseline WITHOUT skill +2. **GREEN Phase:** Add skill, verify compliance +3. **REFACTOR Phase:** Close loopholes + +**REQUIRED SUB-SKILL:** Use superpowers:testing-skills-with-subagents. + +**Test every skill:** Untested skills have issues. + +## Quick Reference + +| Task | Approach | Skills to Use | +| ------------------ | ------------------- | --------------------------------------------- | +| Check existing | `ls skills/` + grep | N/A | +| Enhance skill | Update SKILL.md | writing-skills, testing-skills-with-subagents | +| New skill | Full TDD cycle | writing-skills, testing-skills-with-subagents | +| Add infrastructure | .claude/tools/ | N/A | +| Add docs | docs/ | N/A | +| Exploration | Worktree required | using-git-worktrees | + +## Common Mistakes + +### Skipping Existing Skills Check + +**Problem:** Create new skill when could enhance existing +**Fix:** Always check all 33+ skills first with grep + +### Wrong Directory + +**Problem:** Put infrastructure in skills/, docs in .claude/ +**Fix:** Use structure table above + +### No Worktree + +**Problem:** Work directly in main branch +**Fix:** ALWAYS use worktrees for exploration + +### Format Violations + +**Problem:** Wrong SKILL.md format, breaks auto-activation +**Fix:** Follow exact format from writing-skills + +### Skipping Tests + +**Problem:** Deploy untested skill, breaks in production +**Fix:** Full RED-GREEN-REFACTOR cycle, no exceptions + +### Philosophy Drift + +**Problem:** Add explicit-invocation features to auto-activation project +**Fix:** Check philosophy alignment before integrating + +### Skill Proliferation + +**Problem:** Create many niche skills, hard to discover +**Fix:** High bar for new skills, enhance existing when possible + +## Red Flags - STOP + +- Creating new skill without checking existing 33+ +- Working in main branch instead of worktree +- Infrastructure in skills/ or skills in .claude/tools/ +- No testing plan +- "Port their system" without adaptation +- Explicit invocation in auto-activation project +- Adding complexity without clear benefit + +**All of these mean: Step back, follow the systematic process.** + +## Integration Workflow + +### Full Workflow (New Feature from External Project) + +1. **Analysis** (in worktree) + - Use extracting-patterns-from-projects skill + - Create comprehensive write-up + - Get user approval on approach + +2. **Check Existing** (mandatory) + - List all skills + - Grep for related concepts + - Decide: enhance existing or create new + +3. **Implementation** (in worktree) + - If enhancing: Update SKILL.md + test + - If new skill: Full writing-skills TDD cycle + - If infrastructure: Add to .claude/tools/ + - If docs: Add to docs/ + +4. **Testing** (in worktree) + - Run tests per testing-skills-with-subagents + - Verify integration with existing skills + - Check philosophy alignment + +5. **Deployment** (from worktree) + - Commit in worktree + - Test in worktree + - Merge to main when ready + - Use finishing-a-development-branch + +## Real-World Example + +From amplifier integration (2025-10-23): + +1. ✅ Used extracting-patterns-from-projects for analysis +2. ✅ Created worktree (.worktrees/amplifier-integration) +3. ✅ Comprehensive write-up (docs/amplifier-analysis.md) +4. ✅ Identified 18+ patterns with three-tier priorities +5. ❌ Initially created worktree in wrong location (caught by user) +6. ✅ Fixed by following using-git-worktrees skill +7. → Now writing these two skills to prevent future issues + +**Lessons:** + +- Follow existing skills even when you think you know +- User caught mistake because skill wasn't there yet +- These skills will prevent this in 7th, 8th, 9th attempts + +## Integration + +**Required skills:** + +- **extracting-patterns-from-projects** - For analysis phase +- **using-git-worktrees** - For isolation +- **writing-skills** - For creating/modifying skills +- **testing-skills-with-subagents** - For validation + +**Pairs with:** + +- **brainstorming** - For design decisions +- **writing-plans** - After approval +- **finishing-a-development-branch** - For cleanup diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 47e545a67..9c46902eb 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -1,5 +1,5 @@ --- -name: executing-plans +name: Executing Plans description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches --- @@ -16,28 +16,42 @@ Load plan, review critically, execute tasks in batches, report for review betwee ## The Process ### Step 1: Load and Review Plan + 1. Read plan file 2. Review critically - identify any questions or concerns about the plan 3. If concerns: Raise them with your human partner before starting 4. If no concerns: Create TodoWrite and proceed ### Step 2: Execute Batch + **Default: First 3 tasks** For each task: + 1. Mark as in_progress 2. Follow each step exactly (plan has bite-sized steps) 3. Run verifications as specified -4. Mark as completed +4. **Quick validation** (after completing task, before marking complete): + - **Type check**: If you changed signatures, run type checker (mypy/tsc/etc.) + - **Import validation**: If you changed function/class names, grep for call sites + - **Task-specific test**: If plan specifies a test for this task, run it + - **Fix forward**: If validation fails, fix before next task +5. Mark as completed + +**Exception**: Multi-file refactors that intentionally break across tasks - document the plan and validate at batch boundary instead. ### Step 3: Report + When batch complete: + - Show what was implemented - Show verification output - Say: "Ready for feedback." ### Step 4: Continue + Based on feedback: + - Apply changes if needed - Execute next batch - Repeat until complete @@ -45,6 +59,7 @@ Based on feedback: ### Step 5: Complete Development After all tasks complete and verified: + - Announce: "I'm using the finishing-a-development-branch skill to complete this work." - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice @@ -52,6 +67,7 @@ After all tasks complete and verified: ## When to Stop and Ask for Help **STOP executing immediately when:** + - Hit a blocker mid-batch (missing dependency, test fails, instruction unclear) - Plan has critical gaps preventing starting - You don't understand an instruction @@ -62,12 +78,14 @@ After all tasks complete and verified: ## When to Revisit Earlier Steps **Return to Review (Step 1) when:** + - Partner updates the plan based on your feedback - Fundamental approach needs rethinking **Don't force through blockers** - stop and ask. ## Remember + - Review plan critically first - Follow plan steps exactly - Don't skip verifications diff --git a/skills/extracting-patterns-from-projects/SKILL.md b/skills/extracting-patterns-from-projects/SKILL.md new file mode 100644 index 000000000..b00366f6c --- /dev/null +++ b/skills/extracting-patterns-from-projects/SKILL.md @@ -0,0 +1,336 @@ +--- +name: Extracting Patterns From Projects +description: Use when analyzing external projects for transferable concepts - prevents surface-level copying by requiring systematic analysis, pattern vs architecture distinction, three-tier prioritization, philosophy alignment, and risk assessment before recommendations +--- + +# Extracting Patterns From Projects + +## Overview + +Systematic methodology for analyzing external projects to extract transferable patterns while avoiding copy-paste mistakes. + +**Core principle:** Extract patterns and principles, not architectures. Assess fit before recommending. + +**Announce at start:** "I'm using the extracting-patterns-from-projects skill to systematically analyze this project." + +## When to Use + +Use when: + +- Asked to "see what we can use from project X" +- Comparing projects for inspiration +- Evaluating whether to adopt practices from elsewhere +- Researching how others solved similar problems + +Skip when: + +- Simple feature copying is appropriate +- Projects are too different to compare meaningfully +- You're implementing, not researching + +## Core Pattern + +### ❌ Surface-Level Approach (Baseline Failure) + +```markdown +Analysis: Project X has these features: + +- Agents system +- Hook scripts +- Configuration files + +Recommendation: Add all of these to our project. +``` + +**Problems:** + +- No depth (what makes agents valuable?) +- Copy-paste mentality (architecture, not patterns) +- No prioritization (boil the ocean) +- No fit assessment (does this match our philosophy?) + +### ✅ Pattern Extraction Approach + +```markdown +Analysis of Project X: + +## Pattern Categories + +1. Knowledge Management (DISCOVERIES.md pattern) + - Pattern: Living document for non-obvious solutions + - Value: Prevents repeated problem-solving + - Fit: High (aligns with our documentation focus) + +2. Architecture (Agent-based invocation) + - Pattern: Explicit specialized invocation + - Value: Deep expertise per domain + - Fit: Low (conflicts with our auto-activation approach) + - **Recommendation: Extract agent patterns into our skills system** + +## Three-Tier Priorities + +**Tier 1 (4-6hrs)**: DISCOVERIES.md, decisions/ +**Tier 2 (8-12hrs)**: Transcript hooks, workflow patterns +**Tier 3 (15-20hrs)**: New skills, advanced infrastructure + +## Philosophy Alignment + +✅ Matches: Simplicity, modularity, TDD +⚠️ Differs: Heavy workflows vs lightweight skills +❌ Conflicts: Agent invocation vs auto-activation + +## Risks & Mitigation + +- Risk: Scope creep → Start Tier 1 only +- Risk: Maintenance burden → Prefer docs over code +- Risk: Philosophy drift → Extract patterns, not architectures +``` + +## Systematic Analysis Process + +### 1. Project Exploration (30-60min) + +**For small projects** (< 50 files): + +```bash +# Direct exploration +tree -L 3 +cat README.md +ls -la .github/ .vscode/ docs/ +``` + +**For large projects** (50+ files): +Use parallel read-only subagents: + +```bash +# Set up read-only tools +RO_TOOLS="Read,Glob,Grep,Bash(fd:*),Bash(rg:*),Bash(tree:*),Bash(ls:*)" +DENIED_TOOLS="Write,Edit,Bash(git add:*),Bash(rm:*)" + +# Launch specialized agents in parallel +claude -p "READ-ONLY: Analyze workflow systems (commands, hooks, automation)" \ + --output-format stream-json --allowedTools "$RO_TOOLS" --disallowedTools "$DENIED_TOOLS" & + +claude -p "READ-ONLY: Analyze knowledge management (docs, decisions, discoveries)" \ + --output-format stream-json --allowedTools "$RO_TOOLS" --disallowedTools "$DENIED_TOOLS" & + +wait +``` + +**Document structure:** + +- Directory organization +- Key files and their purposes +- Configuration patterns +- Documentation approach + +### 2. Pattern Identification (20-30min) + +**Ask for each capability found:** + +1. **What's the pattern?** (not just "they have X") +2. **What problem does it solve?** (why does this exist?) +3. **What's the mechanism?** (how does it work?) +4. **What are the trade-offs?** (costs vs benefits) + +**Create pattern catalog:** + +| Pattern | Problem Solved | Mechanism | Trade-offs | +| ---------------- | -------------------------- | ----------------------------------- | ------------------------------- | +| DISCOVERIES.md | Repeated problem-solving | Living doc with Date/Issue/Solution | Requires discipline to maintain | +| Agent invocation | Deep specialized expertise | Explicit context for each domain | Heavier than auto-activation | + +### 3. Philosophy Alignment (15-20min) + +**Compare on key dimensions:** + +```markdown +| Dimension | Source Project | Target Project | Alignment | +| ---------- | ------------------- | ----------------- | ------------------- | +| Activation | Explicit invocation | Auto-activation | ⚠️ Different | +| Complexity | Feature-rich | Ruthlessly simple | ⚠️ Filter needed | +| Structure | Agents (23) | Skills (33) | ⚠️ Extract patterns | +| Testing | Integration-focused | TDD-focused | ✅ Compatible | +``` + +**Alignment levels:** + +- ✅ **Strong**: Core values match, direct adoption possible +- ⚠️ **Moderate**: Different approaches, extract patterns not architectures +- ❌ **Weak**: Fundamental conflicts, learn but don't adopt + +### 4. Priority System (20-30min) + +**Three-tier classification:** + +**Tier 1: Quick Wins** (4-6 hours total) + +- High value, low effort +- No architectural changes needed +- Clear immediate benefit +- Example: Documentation patterns, simple templates + +**Tier 2: High Value** (8-12 hours total) + +- Significant value, moderate effort +- May require some integration work +- Clear benefits outweigh costs +- Example: Workflow enhancements, infrastructure + +**Tier 3: Specialized** (15-20 hours total) + +- Good value but high effort OR specialized use cases +- Consider based on actual need +- Implement only when needed +- Example: Advanced features, new capabilities + +**For each item, document:** + +- Estimated effort (hours) +- Expected value/impact +- Dependencies on other work +- Risk level + +### 5. Risk Assessment (15-20min) + +**Common risks:** + +| Risk | Indicators | Mitigation | +| ------------------ | ----------------------- | ----------------------------------------------------- | +| Scope creep | "Let's add everything!" | Tier 1 only, validate before proceeding | +| Maintenance burden | Many new files/scripts | Prefer docs over code, simple over complex | +| Philosophy drift | Conflicts with values | Extract patterns, reject architectures | +| User adoption | Complex new workflows | Start with infrastructure that enhances existing work | +| Technical debt | Quick hacks | Follow existing quality standards | + +### 6. Comprehensive Write-up (30-45min) + +**Required sections:** + +1. **Executive Summary**: Top recommendations, estimated impact +2. **Project Comparison**: Philosophy alignment table +3. **Category Analysis**: Group patterns by type (5-7 categories) +4. **Three-Tier Recommendations**: With effort estimates +5. **Risk Analysis**: Specific to recommendations +6. **Trade-off Tables**: For each major recommendation +7. **Implementation Sequences**: 2-3 different approaches +8. **File Change Summary**: What will be created/modified + +**Total time for complete analysis:** 2.5-4 hours + +**After write-up:** + +Check if project uses ADR pattern: + +```bash +test -d docs/decisions && echo "ADR available" +``` + +**If this is a major integration decision:** + +- **If ADR available**: Create ADR documenting the decision to integrate (or not integrate) patterns +- **Otherwise**: Store decision rationale with `mem add "Pattern extraction decision: [what] because [why]" --tags "decision,patterns"` + +Major integrations warrant formal decision documentation. + +## Pattern vs Architecture Distinction + +**Critical:** Distinguish patterns from architectures. + +### Architecture (Avoid Copying) + +- "They use an agent system with 23 specialized agents" +- "They have a 5-phase DDD workflow with state management" +- "They use MCP for service communication" + +**Why not:** Target project has different architectural constraints. + +### Pattern (Extract These) + +- "Artifact-driven phases where each stage produces inputs for next" +- "Approval gates at key transitions" +- "Living documentation that updates before code" + +**Why extract:** Patterns adapt to any architecture. + +## Quick Reference + +| Step | Time | Output | +| -------------------- | ------------ | ------------------------------- | +| 1. Explore | 30-60min | Project structure, key files | +| 2. Identify Patterns | 20-30min | Pattern catalog with trade-offs | +| 3. Assess Philosophy | 15-20min | Alignment table | +| 4. Prioritize | 20-30min | Three-tier recommendations | +| 5. Assess Risks | 15-20min | Risk mitigation table | +| 6. Write-up | 30-45min | Comprehensive document | +| **Total** | **2.5-4hrs** | **Complete analysis** | + +## Common Mistakes + +### Surface-Level Analysis + +**Problem:** Quick scan, shallow recommendations +**Fix:** Spend 30min+ in exploration, use parallel agents for large projects + +### Copy-Paste Mentality + +**Problem:** "Add their agents system" +**Fix:** Always ask "What's the pattern?" not "What's the feature?" + +### No Prioritization + +**Problem:** List 20 things without guidance +**Fix:** Force three-tier classification, estimate effort for each + +### Missing Philosophy Check + +**Problem:** Recommend conflicting approaches +**Fix:** Always create alignment table before recommending + +### Ignoring Trade-offs + +**Problem:** Present benefits without costs +**Fix:** Every recommendation needs trade-off table + +### Boiling the Ocean + +**Problem:** Try to implement everything +**Fix:** Recommend Tier 1 only, validate before proceeding + +## Red Flags - STOP + +- Recommending "add their system" without pattern extraction +- No three-tier priorities +- No philosophy alignment assessment +- No risk analysis +- No effort estimates +- Recommendations without trade-offs +- "Implement everything" approach + +**All of these mean: Your analysis is incomplete. Follow the systematic process.** + +## Integration + +**Pairs with:** + +- **using-git-worktrees** - REQUIRED for exploration work +- **brainstorming** - Use for designing integration approach +- **writing-plans** - After approval, create implementation plan + +**Project-specific variants:** + +- **enhancing-superpowers** - Superpowers-specific integration guidance +- Add your own for other projects + +## Real-World Example + +From amplifier analysis (2025-10-23): + +- ✅ Used parallel read-only agents +- ✅ Distinguished patterns from architectures +- ✅ Three-tier priority system (Tier 1: 4-6hrs) +- ✅ Philosophy alignment section +- ✅ Risk assessment with mitigation +- ✅ Trade-off tables for each recommendation +- ✅ Multiple implementation sequences +- **Result:** User can make informed decisions without feature overwhelm diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md index c308b43b4..24be36c8c 100644 --- a/skills/finishing-a-development-branch/SKILL.md +++ b/skills/finishing-a-development-branch/SKILL.md @@ -1,5 +1,5 @@ --- -name: finishing-a-development-branch +name: Finishing a Development Branch description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup --- @@ -25,6 +25,7 @@ npm test / cargo test / pytest / go test ./... ``` **If tests fail:** + ``` Tests failing ( failures). Must fix before completing: @@ -37,7 +38,31 @@ Stop. Don't proceed to Step 2. **If tests pass:** Continue to Step 2. -### Step 2: Determine Base Branch +### Step 2: Documentation Synchronization + +**YOU MUST invoke the documentation-management skill. No exceptions.** + +Skipping documentation verification = drift. Every time. + +```bash +# Use the Skill tool to invoke: documentation-management +``` + +The skill will: + +- Analyze your branch changes via `git diff ...HEAD` +- Identify documentation gaps (README, CHANGELOG, API docs, guides) +- Update all affected files in the same branch +- Verify inline source links are present +- Confirm version bumps for CHANGELOG + +**If documentation is already synchronized:** The skill confirms this quickly. + +**If updates are needed:** The skill makes them comprehensively. + +**Do not proceed to Step 3 until documentation is synchronized.** + +### Step 3: Determine Base Branch ```bash # Try common base branches @@ -46,7 +71,7 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null Or ask: "This branch split from main - is that correct?" -### Step 3: Present Options +### Step 4: Present Options Present exactly these 4 options: @@ -63,7 +88,7 @@ Which option? **Don't add explanation** - keep options concise. -### Step 4: Execute Choice +### Step 5: Execute Choice #### Option 1: Merge Locally @@ -84,26 +109,60 @@ git merge git branch -d ``` -Then: Cleanup worktree (Step 5) +Then: Cleanup worktree (Step 6) #### Option 2: Push and Create PR +**CRITICAL: Analyze the entire branch, not just latest commit.** + ```bash -# Push branch +# 1. Analyze complete branch context +git log ..HEAD --oneline # All commits +git diff ...HEAD | head -100 # Full diff preview + +# 2. Understand transformation +# - What capability was added/fixed/improved? +# - Why was this change needed? +# - What are ALL the major changes across commits? + +# 3. Push branch git push -u origin -# Create PR -gh pr create --title "" --body "$(cat <<'EOF' +# 4. Create PR with complete context +gh pr create --title "<type>(<scope>): <complete feature description>" --body "$(cat <<'EOF' ## Summary -<2-3 bullets of what changed> +[2-3 sentences describing the complete transformation across all commits] -## Test Plan -- [ ] <verification steps> +## Changes +- [Major change 1 across commits] +- [Major change 2 across commits] +- [Major change 3 across commits] EOF )" ``` -Then: Cleanup worktree (Step 5) +**Example - Bad (only latest commit):** + +```bash +# Branch commits: +# - feat(auth): add User model +# - feat(auth): add login endpoint +# - test(auth): add tests +# - fix: typo in comment ← latest + +# ❌ Bad PR title: "fix: typo in comment" +# This misses the entire authentication feature! +``` + +**Example - Good (full branch analysis):** + +```bash +# Same branch, but analyzed completely +# ✅ Good PR title: "feat(auth): add user authentication system" +# ✅ PR body describes all changes: User model, login endpoint, tests +``` + +Then: Cleanup worktree (Step 6) #### Option 3: Keep As-Is @@ -114,6 +173,7 @@ Report: "Keeping branch <name>. Worktree preserved at <path>." #### Option 4: Discard **Confirm first:** + ``` This will permanently delete: - Branch <name> @@ -126,23 +186,26 @@ Type 'discard' to confirm. Wait for exact confirmation. If confirmed: + ```bash git checkout <base-branch> git branch -D <feature-branch> ``` -Then: Cleanup worktree (Step 5) +Then: Cleanup worktree (Step 6) -### Step 5: Cleanup Worktree +### Step 6: Cleanup Worktree **For Options 1, 2, 4:** Check if in worktree: + ```bash git worktree list | grep $(git branch --show-current) ``` If yes: + ```bash git worktree remove <worktree-path> ``` @@ -151,40 +214,88 @@ git worktree remove <worktree-path> ## Quick Reference -| Option | Merge | Push | Keep Worktree | Cleanup Branch | -|--------|-------|------|---------------|----------------| -| 1. Merge locally | ✓ | - | - | ✓ | -| 2. Create PR | - | ✓ | ✓ | - | -| 3. Keep as-is | - | - | ✓ | - | -| 4. Discard | - | - | - | ✓ (force) | +| Option | Merge | Push | Keep Worktree | Cleanup Branch | +| ---------------- | ----- | ---- | ------------- | -------------- | +| 1. Merge locally | ✓ | - | - | ✓ | +| 2. Create PR | - | ✓ | ✓ | - | +| 3. Keep as-is | - | - | ✓ | - | +| 4. Discard | - | - | - | ✓ (force) | ## Common Mistakes **Skipping test verification** + - **Problem:** Merge broken code, create failing PR - **Fix:** Always verify tests before offering options **Open-ended questions** + - **Problem:** "What should I do next?" → ambiguous - **Fix:** Present exactly 4 structured options +## Optional: Clean Commit History + +**Note:** If you follow good commit guidelines from the start, this shouldn't be necessary. + +If your branch has messy commits and you want clean history before PR: + +### When to Clean + +- Multiple "WIP" or "fix" commits +- Logical changes spread across multiple commits +- Want each commit to be independently reviewable + +### How to Clean + +```bash +# Interactive rebase to main +git rebase -i main + +# In editor: +# - Use 'squash' to combine related commits +# - Use 'reword' to improve commit messages +# - Use 'edit' to split commits + +# To split a commit: +# - Mark commit as 'edit' in rebase +# - When it stops: git reset HEAD^ +# - Stage and commit in logical groups +# - Continue: git rebase --continue +``` + +### Logical Grouping + +Group changes by: + +- Feature vs tests vs docs +- Refactoring vs new functionality +- Public API vs implementation details + +Each commit should be independently understandable and (ideally) pass tests. + +**Only do this before pushing/before PR**. Don't rewrite published history. + **Automatic worktree cleanup** + - **Problem:** Remove worktree when might need it (Option 2, 3) - **Fix:** Only cleanup for Options 1 and 4 **No confirmation for discard** + - **Problem:** Accidentally delete work - **Fix:** Require typed "discard" confirmation ## Red Flags **Never:** + - Proceed with failing tests - Merge without verifying tests on result - Delete work without confirmation - Force-push without explicit request **Always:** + - Verify tests before offering options - Present exactly 4 options - Get typed confirmation for Option 4 @@ -193,8 +304,10 @@ git worktree remove <worktree-path> ## Integration **Called by:** + - **subagent-driven-development** (Step 7) - After all tasks complete - **executing-plans** (Step 5) - After all batches complete **Pairs with:** + - **using-git-worktrees** - Cleans up worktree created by that skill diff --git a/skills/inversion-exercise/SKILL.md b/skills/inversion-exercise/SKILL.md new file mode 100644 index 000000000..beb921350 --- /dev/null +++ b/skills/inversion-exercise/SKILL.md @@ -0,0 +1,59 @@ +--- +name: Inversion Exercise +description: Flip core assumptions to reveal hidden constraints and alternative approaches - "what if the opposite were true?" +when_to_use: when stuck on unquestioned assumptions or feeling forced into "the only way" to do something +version: 1.1.0 +--- + +# Inversion Exercise + +## Overview + +Flip every assumption and see what still works. Sometimes the opposite reveals the truth. + +**Core principle:** Inversion exposes hidden assumptions and alternative approaches. + +## Quick Reference + +| Normal Assumption | Inverted | What It Reveals | +| ------------------------- | -------------------------------- | -------------------------- | +| Cache to reduce latency | Add latency to enable caching | Debouncing patterns | +| Pull data when needed | Push data before needed | Prefetching, eager loading | +| Handle errors when occur | Make errors impossible | Type systems, contracts | +| Build features users want | Remove features users don't need | Simplicity >> addition | +| Optimize for common case | Optimize for worst case | Resilience patterns | + +## Process + +1. **List core assumptions** - What "must" be true? +2. **Invert each systematically** - "What if opposite were true?" +3. **Explore implications** - What would we do differently? +4. **Find valid inversions** - Which actually work somewhere? + +## Example + +**Problem:** Users complain app is slow + +**Normal approach:** Make everything faster (caching, optimization, CDN) + +**Inverted:** Make things intentionally slower in some places + +- Debounce search (add latency → enable better results) +- Rate limit requests (add friction → prevent abuse) +- Lazy load content (delay → reduce initial load) + +**Insight:** Strategic slowness can improve UX + +## Red Flags You Need This + +- "There's only one way to do this" +- Forcing solution that feels wrong +- Can't articulate why approach is necessary +- "This is just how it's done" + +## Remember + +- Not all inversions work (test boundaries) +- Valid inversions reveal context-dependence +- Sometimes opposite is the answer +- Question "must be" statements diff --git a/skills/meta-pattern-recognition/SKILL.md b/skills/meta-pattern-recognition/SKILL.md new file mode 100644 index 000000000..5c0617f27 --- /dev/null +++ b/skills/meta-pattern-recognition/SKILL.md @@ -0,0 +1,54 @@ +--- +name: Meta-Pattern Recognition +description: Spot patterns appearing in 3+ domains to find universal principles +when_to_use: when noticing the same pattern across 3+ different domains or experiencing déjà vu in problem-solving +version: 1.1.0 +--- + +# Meta-Pattern Recognition + +## Overview + +When the same pattern appears in 3+ domains, it's probably a universal principle worth extracting. + +**Core principle:** Find patterns in how patterns emerge. + +## Quick Reference + +| Pattern Appears In | Abstract Form | Where Else? | +| ---------------------------------- | ------------------------------------------- | -------------------------------------- | +| CPU/DB/HTTP/DNS caching | Store frequently-accessed data closer | LLM prompt caching, CDN | +| Layering (network/storage/compute) | Separate concerns into abstraction levels | Architecture, organization | +| Queuing (message/task/request) | Decouple producer from consumer with buffer | Event systems, async processing | +| Pooling (connection/thread/object) | Reuse expensive resources | Memory management, resource governance | + +## Process + +1. **Spot repetition** - See same shape in 3+ places +2. **Extract abstract form** - Describe independent of any domain +3. **Identify variations** - How does it adapt per domain? +4. **Check applicability** - Where else might this help? + +## Example + +**Pattern spotted:** Rate limiting in API throttling, traffic shaping, circuit breakers, admission control + +**Abstract form:** Bound resource consumption to prevent exhaustion + +**Variation points:** What resource, what limit, what happens when exceeded + +**New application:** LLM token budgets (same pattern - prevent context window exhaustion) + +## Red Flags You're Missing Meta-Patterns + +- "This problem is unique" (probably not) +- Multiple teams independently solving "different" problems identically +- Reinventing wheels across domains +- "Haven't we done something like this?" (yes, find it) + +## Remember + +- 3+ domains = likely universal +- Abstract form reveals new applications +- Variations show adaptation points +- Universal patterns are battle-tested diff --git a/skills/predict-issues/SKILL.md b/skills/predict-issues/SKILL.md new file mode 100644 index 000000000..dc917497d --- /dev/null +++ b/skills/predict-issues/SKILL.md @@ -0,0 +1,159 @@ +--- +name: Predicting Issues +description: Use when completing features, before deployment, or during code reviews - identifies potential problems through systematic risk analysis (likelihood × impact × timeline × effort) +--- + +# Predict Issues + +## Overview + +Proactive problem identification prevents issues before they impact projects. Analyze codebases for patterns that commonly lead to problems, assess risk systematically, and provide actionable recommendations with priority levels. + +## When to Use + +- After implementing features +- Before deployment +- During architecture reviews +- When evaluating technical decisions +- During code reviews for new functionality + +## Risk Assessment Framework + +Evaluate each potential issue across four dimensions: + +| Dimension | Assessment | +| -------------- | -------------------------------------------------------------------------------- | +| **Likelihood** | How probable is this issue? Consider code patterns, usage patterns, scale trends | +| **Impact** | How severe would consequences be? Downtime, data loss, security breach, poor UX | +| **Timeline** | When might this become a problem? Immediate, weeks, months, at 10x scale | +| **Effort** | How hard to fix now vs later? Technical debt cost, refactoring complexity | + +## Security-Specific Risk Analysis + +When analyzing potential security issues: + +### Additional Risk Dimensions + +- **Exploitability**: How easily can this be exploited? (trivial/moderate/difficult) +- **Exposure**: What's exposed? (credentials/data/system access) +- **Blast radius**: Impact if exploited? (single user/all users/system compromise) + +### Common Security Anti-patterns to Check + +1. **Credentials in code**: Hardcoded API keys, passwords, tokens +2. **Injection vulnerabilities**: SQL injection, command injection, XSS +3. **Broken authentication**: Weak session management, missing validation +4. **Insecure dependencies**: Known CVEs in dependencies +5. **Insufficient logging**: Can't detect or investigate incidents +6. **Missing input validation**: Trusting user input without sanitization + +### Risk Scoring for Security Issues + +```text +Security Risk = Exploitability × Exposure × Blast Radius + +Examples: +- Hardcoded API key in public repo: 1.0 × 1.0 × 0.8 = 0.80 (CRITICAL) +- Missing input validation on admin endpoint: 0.7 × 0.9 × 0.9 = 0.57 (HIGH) +- Outdated dependency with theoretical vulnerability: 0.3 × 0.5 × 0.6 = 0.09 (LOW) +``` + +Prioritize by exploitability first, exposure second, blast radius third. + +## Problem Categories + +Focus analysis on these common categories: + +**Performance** + +- O(n²) algorithms that break at scale +- Memory leaks and resource exhaustion +- Inefficient database queries (N+1, missing indexes) +- Unoptimized API calls + +**Maintainability** + +- High cyclomatic complexity +- Poor naming and unclear intent +- Tight coupling between components +- Code duplication across modules + +**Security** + +- Input validation gaps +- Exposed secrets or credentials +- Weak authentication patterns +- Missing authorization checks + +**Scalability** + +- Hardcoded limits and assumptions +- Single points of failure +- Stateful designs that don't scale horizontally +- Resource bottlenecks + +## Analysis Process + +1. **Identify risk areas**: Use Grep to find problematic patterns, Glob to analyze file structure growth, Read to examine complex functions +2. **Assess each issue**: Apply risk framework (likelihood × impact × timeline × effort) +3. **Prioritize findings**: Rank by risk level (Critical/High/Medium/Low) +4. **Provide recommendations**: Specific, actionable fixes with effort estimates + +## Output Format + +For each prediction: + +- **Location**: Specific file and line references (e.g., [auth.ts:42](auth.ts#L42)) +- **Problem**: What pattern will cause issues and why +- **Risk assessment**: Likelihood, impact, timeline, effort to fix +- **Recommendation**: Concrete steps to prevent the problem +- **Priority**: Critical/High/Medium/Low based on risk dimensions + +## Common Patterns to Check + +**Complexity hotspots** + +- Functions over 50 lines +- Files with high change frequency +- Deep nesting levels (>3) + +**Performance concerns** + +- Nested loops over collections +- Synchronous operations in critical paths +- Missing pagination for list operations + +**Architecture stress points** + +- Circular dependencies +- God objects with too many responsibilities +- Integration points without error handling + +**Technical debt indicators** + +- TODO/FIXME comments accumulating +- Commented-out code blocks +- Temporary workarounds still present + +## Tracking Predictions + +After analysis, ask user how to track findings: + +**Available options:** + +- **decisions/** - Create ADR for architectural choices (if `docs/decisions/` exists) +- **discoveries/** - Document known issues and prevention (if `docs/discoveries/DISCOVERIES.md` exists) +- **Memory** - Store risk assessments using `mem add` for personal reference +- **TodoWrite** - Create structured task list for systematic review +- **Summary only** - Provide report without creating artifacts + +Check which options are available: + +```bash +test -d docs/decisions && echo "ADR available" +test -f docs/discoveries/DISCOVERIES.md && echo "DISCOVERIES available" +``` + +Present only available options to user. + +Avoid AI attribution, Claude Code watermarks, or assistant signatures in issues or reports. diff --git a/skills/preserving-productive-tensions/SKILL.md b/skills/preserving-productive-tensions/SKILL.md new file mode 100644 index 000000000..c2a5a0a12 --- /dev/null +++ b/skills/preserving-productive-tensions/SKILL.md @@ -0,0 +1,165 @@ +--- +name: Preserving Productive Tensions +description: Recognize when disagreements reveal valuable context, preserve multiple valid approaches instead of forcing premature resolution +when_to_use: when oscillating between equally valid approaches that optimize for different legitimate priorities +version: 1.1.0 +--- + +# Preserving Productive Tensions + +## Overview + +Some tensions aren't problems to solve - they're valuable information to preserve. When multiple approaches are genuinely valid in different contexts, forcing a choice destroys flexibility. + +**Core principle:** Preserve tensions that reveal context-dependence. Force resolution only when necessary. + +## Recognizing Productive Tensions + +**A tension is productive when:** + +- Both approaches optimize for different valid priorities (cost vs latency, simplicity vs features) +- The "better" choice depends on deployment context, not technical superiority +- Different users/deployments would choose differently +- The trade-off is real and won't disappear with clever engineering +- Stakeholders have conflicting valid concerns + +**A tension needs resolution when:** + +- Implementation cost of preserving both is prohibitive +- The approaches fundamentally conflict (can't coexist) +- There's clear technical superiority for this specific use case +- It's a one-way door (choice locks architecture) +- Preserving both adds complexity without value + +## Preservation Patterns + +### Pattern 1: Configuration + +Make the choice configurable rather than baked into architecture: + +```python +class Config: + mode: Literal["optimize_cost", "optimize_latency"] + # Each mode gets clean, simple implementation +``` + +**When to use:** Both approaches are architecturally compatible, switching is runtime decision + +### Pattern 2: Parallel Implementations + +Maintain both as separate clean modules with shared contract: + +```python +# processor/batch.py - optimizes for cost +# processor/stream.py - optimizes for latency +# Both implement: def process(data) -> Result +``` + +**When to use:** Approaches diverge significantly, but share same interface + +### Pattern 3: Documented Trade-off + +Capture the tension explicitly in documentation/decision records: + +```markdown +## Unresolved Tension: Authentication Strategy + +**Option A: JWT** - Stateless, scales easily, but token revocation is hard +**Option B: Sessions** - Easy revocation, but requires shared state + +**Why unresolved:** Different deployments need different trade-offs +**Decision deferred to:** Deployment configuration +**Review trigger:** If 80% of deployments choose one option +``` + +**When to use:** Can't preserve both in code, but need to document the choice was deliberate + +## Red Flags - You're Forcing Resolution + +- Asking "which is best?" when both are valid +- "We need to pick one" without explaining why +- Choosing based on your preference vs user context +- Resolving tensions to "make progress" when preserving them IS progress +- Forcing consensus when diversity is valuable + +**All of these mean: STOP. Consider preserving the tension.** + +## When to Force Resolution + +**You SHOULD force resolution when:** + +1. **Implementation cost is prohibitive** + - Building/maintaining both would slow development significantly + - Team doesn't have bandwidth for parallel approaches + +2. **Fundamental conflict** + - Approaches make contradictory architectural assumptions + - Can't cleanly separate concerns + +3. **Clear technical superiority** + - One approach is objectively better for this specific context + - Not "I prefer X" but "X solves our constraints, Y doesn't" + +4. **One-way door** + - Choice locks us into an architecture + - Migration between options would be expensive + +5. **Simplicity requires choice** + - Preserving both genuinely adds complexity + - YAGNI: Don't build both if we only need one + +**Ask explicitly:** "Should I pick one, or preserve both as options?" + +## Documentation Format + +When preserving tensions, document clearly: + +```markdown +## Tension: [Name] + +**Context:** [Why this tension exists] + +**Option A:** [Approach] + +- Optimizes for: [Priority] +- Trade-off: [Cost] +- Best when: [Context] + +**Option B:** [Approach] + +- Optimizes for: [Different priority] +- Trade-off: [Different cost] +- Best when: [Different context] + +**Preservation strategy:** [Configuration/Parallel/Documented] + +**Resolution trigger:** [Conditions that would force choosing one] +``` + +## Examples + +### Productive Tension (Preserve) + +"Should we optimize for cost or latency?" + +- **Answer:** Make it configurable - different deployments need different trade-offs + +### Technical Decision (Resolve) + +"Should we use SSE or WebSockets?" + +- **Answer:** SSE - we only need one-way communication, simpler implementation + +### Business Decision (Defer) + +"Should we support offline mode?" + +- **Answer:** Don't preserve both - ask stakeholder to decide based on user needs + +## Remember + +- Tensions between valid priorities are features, not bugs +- Premature consensus destroys valuable flexibility +- Configuration > forced choice (when reasonable) +- Document trade-offs explicitly +- Resolution is okay when justified diff --git a/skills/receiving-code-review/SKILL.md b/skills/receiving-code-review/SKILL.md index 85d8b0362..f105e80bf 100644 --- a/skills/receiving-code-review/SKILL.md +++ b/skills/receiving-code-review/SKILL.md @@ -1,5 +1,5 @@ --- -name: receiving-code-review +name: Receiving Code Review description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation --- @@ -27,11 +27,13 @@ WHEN receiving code review feedback: ## Forbidden Responses **NEVER:** + - "You're absolutely right!" (explicit CLAUDE.md violation) - "Great point!" / "Excellent feedback!" (performative) - "Let me implement that now" (before verification) **INSTEAD:** + - Restate the technical requirement - Ask clarifying questions - Push back with technical reasoning if wrong @@ -48,6 +50,7 @@ WHY: Items may be related. Partial understanding = wrong implementation. ``` **Example:** + ``` your human partner: "Fix 1-6" You understand 1,2,3,6. Unclear on 4,5. @@ -59,12 +62,14 @@ You understand 1,2,3,6. Unclear on 4,5. ## Source-Specific Handling ### From your human partner + - **Trusted** - implement after understanding - **Still ask** if scope unclear - **No performative agreement** - **Skip to action** or technical acknowledgment ### From External Reviewers + ``` BEFORE implementing: 1. Check: Technically correct for THIS codebase? @@ -97,6 +102,34 @@ IF reviewer suggests "implementing properly": **your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it." +## Pattern Alignment Check + +Before implementing reviewer feedback, check for existing patterns: + +### If Reviewer Says: "Extract this to a helper function" + +1. **Search**: Do similar helpers exist already? + ```bash + rg "def.*helper" --type py + grep -r "formatUser" src/ + ``` +2. **Compare**: If found, does existing helper solve same problem? +3. **Decide**: + - Use existing helper (best) + - Extend existing helper to handle both cases (good) + - Create new helper only if truly different (rare) + +### If Reviewer Says: "This pattern seems complex" + +1. **Search**: How do we solve similar problems elsewhere? +2. **Compare**: Is your approach consistent or outlier? +3. **Decide**: + - If yours is outlier: Adopt codebase pattern (consistency) + - If yours is better: Keep yours, potentially refactor others later + - If equal: Discuss with your human partner + +Don't create new patterns when existing ones solve the problem. Consistency > novelty. + ## Implementation Order ``` @@ -113,6 +146,7 @@ FOR multi-item feedback: ## When To Push Back Push back when: + - Suggestion breaks existing functionality - Reviewer lacks full context - Violates YAGNI (unused feature) @@ -121,6 +155,7 @@ Push back when: - Conflicts with your human partner's architectural decisions **How to push back:** + - Use technical reasoning, not defensiveness - Ask specific questions - Reference working tests/code @@ -131,6 +166,7 @@ Push back when: ## Acknowledging Correct Feedback When feedback IS correct: + ``` ✅ "Fixed. [Brief description of what changed]" ✅ "Good catch - [specific issue]. Fixed in [location]." @@ -150,6 +186,7 @@ When feedback IS correct: ## Gracefully Correcting Your Pushback If you pushed back and were wrong: + ``` ✅ "You were right - I checked [X] and it does [Y]. Implementing now." ✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing." @@ -163,37 +200,41 @@ State the correction factually and move on. ## Common Mistakes -| Mistake | Fix | -|---------|-----| -| Performative agreement | State requirement or just act | -| Blind implementation | Verify against codebase first | -| Batch without testing | One at a time, test each | -| Assuming reviewer is right | Check if breaks things | -| Avoiding pushback | Technical correctness > comfort | -| Partial implementation | Clarify all items first | +| Mistake | Fix | +| ---------------------------- | ----------------------------------- | +| Performative agreement | State requirement or just act | +| Blind implementation | Verify against codebase first | +| Batch without testing | One at a time, test each | +| Assuming reviewer is right | Check if breaks things | +| Avoiding pushback | Technical correctness > comfort | +| Partial implementation | Clarify all items first | | Can't verify, proceed anyway | State limitation, ask for direction | ## Real Examples **Performative Agreement (Bad):** + ``` Reviewer: "Remove legacy code" ❌ "You're absolutely right! Let me remove that..." ``` **Technical Verification (Good):** + ``` Reviewer: "Remove legacy code" ✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?" ``` **YAGNI (Good):** + ``` Reviewer: "Implement proper metrics tracking with database, date filters, CSV export" ✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?" ``` **Unclear Item (Good):** + ``` your human partner: "Fix items 1-6" You understand 1,2,3,6. Unclear on 4,5. diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index f8b1a5652..a9ac6e1d9 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/skills/requesting-code-review/SKILL.md @@ -1,5 +1,5 @@ --- -name: requesting-code-review +name: Requesting Code Review description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches superpowers:code-reviewer subagent to review implementation against plan or requirements before proceeding --- @@ -12,11 +12,13 @@ Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. ## When to Request Review **Mandatory:** + - After each task in subagent-driven development - After completing major feature - Before merge to main **Optional but valuable:** + - When stuck (fresh perspective) - Before refactoring (baseline check) - After fixing complex bug @@ -24,6 +26,7 @@ Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. ## How to Request **1. Get git SHAs:** + ```bash BASE_SHA=$(git rev-parse HEAD~1) # or origin/main HEAD_SHA=$(git rev-parse HEAD) @@ -34,6 +37,7 @@ HEAD_SHA=$(git rev-parse HEAD) Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md` **Placeholders:** + - `{WHAT_WAS_IMPLEMENTED}` - What you just built - `{PLAN_OR_REQUIREMENTS}` - What it should do - `{BASE_SHA}` - Starting commit @@ -41,6 +45,7 @@ Use Task tool with superpowers:code-reviewer type, fill template at `code-review - `{DESCRIPTION}` - Brief summary **3. Act on feedback:** + - Fix Critical issues immediately - Fix Important issues before proceeding - Note Minor issues for later @@ -77,27 +82,32 @@ You: [Fix progress indicators] ## Integration with Workflows **Subagent-Driven Development:** + - Review after EACH task - Catch issues before they compound - Fix before moving to next task **Executing Plans:** + - Review after each batch (3 tasks) - Get feedback, apply, continue **Ad-Hoc Development:** + - Review before merge - Review when stuck ## Red Flags **Never:** + - Skip review because "it's simple" - Ignore Critical issues - Proceed with unfixed Important issues - Argue with valid technical feedback **If reviewer wrong:** + - Push back with technical reasoning - Show code/tests that prove it works - Request clarification diff --git a/skills/requesting-code-review/code-reviewer.md b/skills/requesting-code-review/code-reviewer.md index 3c427c91b..0b0a51906 100644 --- a/skills/requesting-code-review/code-reviewer.md +++ b/skills/requesting-code-review/code-reviewer.md @@ -3,6 +3,7 @@ You are reviewing code changes for production readiness. **Your task:** + 1. Review {WHAT_WAS_IMPLEMENTED} 2. Compare against {PLAN_OR_REQUIREMENTS} 3. Check code quality, architecture, testing @@ -30,6 +31,7 @@ git diff {BASE_SHA}..{HEAD_SHA} ## Review Checklist **Code Quality:** + - Clean separation of concerns? - Proper error handling? - Type safety (if applicable)? @@ -37,24 +39,28 @@ git diff {BASE_SHA}..{HEAD_SHA} - Edge cases handled? **Architecture:** + - Sound design decisions? - Scalability considerations? - Performance implications? - Security concerns? **Testing:** + - Tests actually test logic (not mocks)? - Edge cases covered? - Integration tests where needed? - All tests passing? **Requirements:** + - All plan requirements met? - Implementation matches spec? - No scope creep? - Breaking changes documented? **Production Readiness:** + - Migration strategy (if schema changes)? - Backward compatibility considered? - Documentation complete? @@ -63,26 +69,32 @@ git diff {BASE_SHA}..{HEAD_SHA} ## Output Format ### Strengths + [What's well done? Be specific.] ### Issues #### Critical (Must Fix) + [Bugs, security issues, data loss risks, broken functionality] #### Important (Should Fix) + [Architecture problems, missing features, poor error handling, test gaps] #### Minor (Nice to Have) + [Code style, optimization opportunities, documentation improvements] **For each issue:** + - File:line reference - What's wrong - Why it matters - How to fix (if not obvious) ### Recommendations + [Improvements for code quality, architecture, or process] ### Assessment @@ -94,6 +106,7 @@ git diff {BASE_SHA}..{HEAD_SHA} ## Critical Rules **DO:** + - Categorize by actual severity (not everything is Critical) - Be specific (file:line, not vague) - Explain WHY issues matter @@ -101,6 +114,7 @@ git diff {BASE_SHA}..{HEAD_SHA} - Give clear verdict **DON'T:** + - Say "looks good" without checking - Mark nitpicks as Critical - Give feedback on code you didn't review diff --git a/skills/root-cause-tracing/SKILL.md b/skills/root-cause-tracing/SKILL.md index 823ed1eee..1ac9d066e 100644 --- a/skills/root-cause-tracing/SKILL.md +++ b/skills/root-cause-tracing/SKILL.md @@ -1,5 +1,5 @@ --- -name: root-cause-tracing +name: Root Cause Tracing description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior --- @@ -29,6 +29,7 @@ digraph when_to_use { ``` **Use when:** + - Error happens deep in execution (not at entry point) - Stack trace shows long call chain - Unclear where invalid data originated @@ -37,17 +38,21 @@ digraph when_to_use { ## The Tracing Process ### 1. Observe the Symptom + ``` Error: git init failed in /Users/jesse/project/packages/core ``` ### 2. Find Immediate Cause + **What code directly causes this?** + ```typescript -await execFileAsync('git', ['init'], { cwd: projectDir }); +await execFileAsync("git", ["init"], { cwd: projectDir }); ``` ### 3. Ask: What Called This? + ```typescript WorktreeManager.createSessionWorktree(projectDir, sessionId) → called by Session.initializeWorkspace() @@ -56,16 +61,20 @@ WorktreeManager.createSessionWorktree(projectDir, sessionId) ``` ### 4. Keep Tracing Up + **What value was passed?** + - `projectDir = ''` (empty string!) - Empty string as `cwd` resolves to `process.cwd()` - That's the source code directory! ### 5. Find Original Trigger + **Where did empty string come from?** + ```typescript const context = setupCoreTest(); // Returns { tempDir: '' } -Project.create('name', context.tempDir); // Accessed before beforeEach! +Project.create("name", context.tempDir); // Accessed before beforeEach! ``` ## Adding Stack Traces @@ -76,25 +85,27 @@ When you can't trace manually, add instrumentation: // Before the problematic operation async function gitInit(directory: string) { const stack = new Error().stack; - console.error('DEBUG git init:', { + console.error("DEBUG git init:", { directory, cwd: process.cwd(), nodeEnv: process.env.NODE_ENV, stack, }); - await execFileAsync('git', ['init'], { cwd: directory }); + await execFileAsync("git", ["init"], { cwd: directory }); } ``` **Critical:** Use `console.error()` in tests (not logger - may not show) **Run and capture:** + ```bash npm test 2>&1 | grep 'DEBUG git init' ``` **Analyze stack traces:** + - Look for test file names - Find the line number triggering the call - Identify the pattern (same test? same parameter?) @@ -116,6 +127,7 @@ Runs tests one-by-one, stops at first polluter. See script for usage. **Symptom:** `.git` created in `packages/core/` (source code) **Trace chain:** + 1. `git init` runs in `process.cwd()` ← empty cwd parameter 2. WorktreeManager called with empty projectDir 3. Session.create() passed empty string @@ -127,11 +139,35 @@ Runs tests one-by-one, stops at first polluter. See script for usage. **Fix:** Made tempDir a getter that throws if accessed before beforeEach **Also added defense-in-depth:** + - Layer 1: Project.create() validates directory - Layer 2: WorkspaceManager validates not empty - Layer 3: NODE_ENV guard refuses git init outside tmpdir - Layer 4: Stack trace logging before git init +## Documenting Discoveries + +After tracing to source and fixing: + +**Check if project uses discoveries pattern:** + +```bash +test -f docs/discoveries/DISCOVERIES.md && echo "Discoveries file exists" +``` + +**If `docs/discoveries/DISCOVERIES.md` exists:** + +- Document the complete trace path +- Record the root cause discovered +- Describe the solution applied +- Add prevention guidance +- Help others recognize this pattern faster + +**If file doesn't exist:** + +- Use `mem add "Root cause trace: [symptom] → [immediate cause] → [source]. Fixed at [location]" --tags "discovery,trace,project"` +- Store for personal reference in future debugging + ## Key Principle ```dot @@ -168,6 +204,7 @@ digraph principle { ## Real-World Impact From debugging session (2025-10-03): + - Found root cause through 5-level trace - Fixed at source (getter validation) - Added 4 layers of defense diff --git a/skills/scale-game/SKILL.md b/skills/scale-game/SKILL.md new file mode 100644 index 000000000..a92f00483 --- /dev/null +++ b/skills/scale-game/SKILL.md @@ -0,0 +1,66 @@ +--- +name: Scale Game +description: Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths hidden at normal scales +when_to_use: when uncertain about scalability, edge cases unclear, or validating architecture for production volumes +version: 1.1.0 +--- + +# Scale Game + +## Overview + +Test your approach at extreme scales to find what breaks and what surprisingly survives. + +**Core principle:** Extremes expose fundamental truths hidden at normal scales. + +## Quick Reference + +| Scale Dimension | Test At Extremes | What It Reveals | +| --------------- | --------------------------- | ----------------------------------- | +| Volume | 1 item vs 1B items | Algorithmic complexity limits | +| Speed | Instant vs 1 year | Async requirements, caching needs | +| Users | 1 user vs 1B users | Concurrency issues, resource limits | +| Duration | Milliseconds vs years | Memory leaks, state growth | +| Failure rate | Never fails vs always fails | Error handling adequacy | + +## Process + +1. **Pick dimension** - What could vary extremely? +2. **Test minimum** - What if this was 1000x smaller/faster/fewer? +3. **Test maximum** - What if this was 1000x bigger/slower/more? +4. **Note what breaks** - Where do limits appear? +5. **Note what survives** - What's fundamentally sound? + +## Examples + +### Example 1: Error Handling + +**Normal scale:** "Handle errors when they occur" works fine +**At 1B scale:** Error volume overwhelms logging, crashes system +**Reveals:** Need to make errors impossible (type systems) or expect them (chaos engineering) + +### Example 2: Synchronous APIs + +**Normal scale:** Direct function calls work +**At global scale:** Network latency makes synchronous calls unusable +**Reveals:** Async/messaging becomes survival requirement, not optimization + +### Example 3: In-Memory State + +**Normal duration:** Works for hours/days +**At years:** Memory grows unbounded, eventual crash +**Reveals:** Need persistence or periodic cleanup, can't rely on memory + +## Red Flags You Need This + +- "It works in dev" (but will it work in production?) +- No idea where limits are +- "Should scale fine" (without testing) +- Surprised by production behavior + +## Remember + +- Extremes reveal fundamentals +- What works at one scale fails at another +- Test both directions (bigger AND smaller) +- Use insights to validate architecture early diff --git a/skills/sharing-skills/SKILL.md b/skills/sharing-skills/SKILL.md index eaff38757..bdd863f9f 100644 --- a/skills/sharing-skills/SKILL.md +++ b/skills/sharing-skills/SKILL.md @@ -1,5 +1,5 @@ --- -name: sharing-skills +name: Sharing Skills description: Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository --- @@ -14,12 +14,14 @@ Contribute skills from your local branch back to the upstream repository. ## When to Share **Share when:** + - Skill applies broadly (not project-specific) - Pattern/technique others would benefit from - Well-tested and documented - Follows writing-skills guidelines **Keep personal when:** + - Project-specific or organization-specific - Experimental or unstable - Contains sensitive information @@ -146,6 +148,7 @@ Addresses common async pitfalls like race conditions, improper error handling, a Once your PR is merged: 1. Sync your local main branch: + ```bash cd ~/.config/superpowers/skills/ git checkout main @@ -154,6 +157,7 @@ git push origin main ``` 2. Delete the feature branch: + ```bash git branch -d "add-${skill_name}-skill" git push origin --delete "add-${skill_name}-skill" @@ -162,18 +166,22 @@ git push origin --delete "add-${skill_name}-skill" ## Troubleshooting **"gh: command not found"** + - Install GitHub CLI: https://cli.github.com/ - Authenticate: `gh auth login` **"Permission denied (publickey)"** + - Check SSH keys: `gh auth status` - Set up SSH: https://docs.github.com/en/authentication **"Skill already exists"** + - You're creating a modified version - Consider different skill name or coordinate with the skill's maintainer **PR merge conflicts** + - Rebase on latest upstream: `git fetch upstream && git rebase upstream/main` - Resolve conflicts - Force push: `git push -f origin your-branch` @@ -183,6 +191,7 @@ git push origin --delete "add-${skill_name}-skill" **Do NOT batch multiple skills in one PR.** Each skill should: + - Have its own feature branch - Have its own PR - Be independently reviewable diff --git a/skills/simplification-cascades/SKILL.md b/skills/simplification-cascades/SKILL.md new file mode 100644 index 000000000..c0e5373e5 --- /dev/null +++ b/skills/simplification-cascades/SKILL.md @@ -0,0 +1,80 @@ +--- +name: Simplification Cascades +description: Find one insight that eliminates multiple components - "if this is true, we don't need X, Y, or Z" +when_to_use: when implementing the same concept multiple ways, accumulating special cases, or complexity is spiraling +version: 1.1.0 +--- + +# Simplification Cascades + +## Overview + +Sometimes one insight eliminates 10 things. Look for the unifying principle that makes multiple components unnecessary. + +**Core principle:** "Everything is a special case of..." collapses complexity dramatically. + +## Quick Reference + +| Symptom | Likely Cascade | +| ------------------------------ | ------------------------------------ | +| Same thing implemented 5+ ways | Abstract the common pattern | +| Growing special case list | Find the general case | +| Complex rules with exceptions | Find the rule that has no exceptions | +| Excessive config options | Find defaults that work for 95% | + +## The Pattern + +**Look for:** + +- Multiple implementations of similar concepts +- Special case handling everywhere +- "We need to handle A, B, C, D differently..." +- Complex rules with many exceptions + +**Ask:** "What if they're all the same thing underneath?" + +## Examples + +### Cascade 1: Stream Abstraction + +**Before:** Separate handlers for batch/real-time/file/network data +**Insight:** "All inputs are streams - just different sources" +**After:** One stream processor, multiple stream sources +**Eliminated:** 4 separate implementations + +### Cascade 2: Resource Governance + +**Before:** Session tracking, rate limiting, file validation, connection pooling (all separate) +**Insight:** "All are per-entity resource limits" +**After:** One ResourceGovernor with 4 resource types +**Eliminated:** 4 custom enforcement systems + +### Cascade 3: Immutability + +**Before:** Defensive copying, locking, cache invalidation, temporal coupling +**Insight:** "Treat everything as immutable data + transformations" +**After:** Functional programming patterns +**Eliminated:** Entire classes of synchronization problems + +## Process + +1. **List the variations** - What's implemented multiple ways? +2. **Find the essence** - What's the same underneath? +3. **Extract abstraction** - What's the domain-independent pattern? +4. **Test it** - Do all cases fit cleanly? +5. **Measure cascade** - How many things become unnecessary? + +## Red Flags You're Missing a Cascade + +- "We just need to add one more case..." (repeating forever) +- "These are all similar but different" (maybe they're the same?) +- Refactoring feels like whack-a-mole (fix one, break another) +- Growing configuration file +- "Don't touch that, it's complicated" (complexity hiding pattern) + +## Remember + +- Simplification cascades = 10x wins, not 10% improvements +- One powerful abstraction > ten clever hacks +- The pattern is usually already there, just needs recognition +- Measure in "how many things can we delete?" diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 1e1292cb9..32034f707 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -1,5 +1,5 @@ --- -name: subagent-driven-development +name: Subagent-Driven Development description: Use when executing implementation plans with independent tasks in the current session - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates --- @@ -12,17 +12,20 @@ Execute plan by dispatching fresh subagent per task, with code review after each ## Overview **vs. Executing Plans (parallel session):** + - Same session (no context switch) - Fresh subagent per task (no context pollution) - Code review after each task (catch issues early) - Faster iteration (no human-in-loop between tasks) **When to use:** + - Staying in this session - Tasks are mostly independent - Want continuous progress with quality gates **When NOT to use:** + - Need to review plan first (use executing-plans) - Tasks are tightly coupled (manual execution better) - Plan needs revision (brainstorm first) @@ -38,6 +41,7 @@ Read plan file, create TodoWrite with all tasks. For each task: **Dispatch fresh subagent:** + ``` Task tool (general-purpose): description: "Implement Task N: [task name]" @@ -61,6 +65,7 @@ Task tool (general-purpose): ### 3. Review Subagent's Work **Dispatch code-reviewer subagent:** + ``` Task tool (superpowers:code-reviewer): Use template at requesting-code-review/code-reviewer.md @@ -77,11 +82,13 @@ Task tool (superpowers:code-reviewer): ### 4. Apply Review Feedback **If issues found:** + - Fix Critical issues immediately - Fix Important issues before next task - Note Minor issues **Dispatch follow-up subagent if needed:** + ``` "Fix issues from code review: [list issues]" ``` @@ -95,6 +102,7 @@ Task tool (superpowers:code-reviewer): ### 6. Final Review After all tasks complete, dispatch final code-reviewer: + - Reviews entire implementation - Checks all plan requirements met - Validates overall architecture @@ -102,6 +110,7 @@ After all tasks complete, dispatch final code-reviewer: ### 7. Complete Development After final review passes: + - Announce: "I'm using the finishing-a-development-branch skill to complete this work." - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice @@ -148,42 +157,50 @@ Done! ## Advantages **vs. Manual execution:** + - Subagents follow TDD naturally - Fresh context per task (no confusion) - Parallel-safe (subagents don't interfere) **vs. Executing Plans:** + - Same session (no handoff) - Continuous progress (no waiting) - Review checkpoints automatic **Cost:** + - More subagent invocations - But catches issues early (cheaper than debugging later) ## Red Flags **Never:** + - Skip code review between tasks - Proceed with unfixed Critical issues - Dispatch multiple implementation subagents in parallel (conflicts) - Implement without reading plan task **If subagent fails task:** + - Dispatch fix subagent with specific instructions - Don't try to fix manually (context pollution) ## Integration **Required workflow skills:** + - **writing-plans** - REQUIRED: Creates the plan that this skill executes - **requesting-code-review** - REQUIRED: Review after each task (see Step 3) - **finishing-a-development-branch** - REQUIRED: Complete development after all tasks (see Step 7) **Subagents must use:** + - **test-driven-development** - Subagents follow TDD for each task **Alternative workflow:** + - **executing-plans** - Use for parallel session instead of same-session execution See code-reviewer template: requesting-code-review/code-reviewer.md diff --git a/skills/systematic-debugging/CREATION-LOG.md b/skills/systematic-debugging/CREATION-LOG.md index 024d00a5e..e9ddb5910 100644 --- a/skills/systematic-debugging/CREATION-LOG.md +++ b/skills/systematic-debugging/CREATION-LOG.md @@ -5,6 +5,7 @@ Reference example of extracting, structuring, and bulletproofing a critical skil ## Source Material Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`: + - 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation) - Core mandate: ALWAYS find root cause, NEVER fix symptoms - Rules designed to resist time pressure and rationalization @@ -12,12 +13,14 @@ Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`: ## Extraction Decisions **What to include:** + - Complete 4-phase framework with all rules - Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze") - Pressure-resistant language ("even if faster", "even if I seem in a hurry") - Concrete steps for each phase **What to leave out:** + - Project-specific context - Repetitive variations of same rule - Narrative explanations (condensed to principles) @@ -36,18 +39,21 @@ Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`: Framework designed to resist rationalization under pressure: ### Language Choices + - "ALWAYS" / "NEVER" (not "should" / "try to") - "even if faster" / "even if I seem in a hurry" - "STOP and re-analyze" (explicit pause) - "Don't skip past" (catches the actual behavior) ### Structural Defenses + - **Phase 1 required** - Can't skip to implementation - **Single hypothesis rule** - Forces thinking, prevents shotgun fixes - **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action - **Anti-patterns section** - Shows exactly what shortcuts look like ### Redundancy + - Root cause mandate in overview + when_to_use + Phase 1 + implementation rules - "NEVER fix symptom" appears 4 times in different contexts - Each phase has explicit "don't skip" guidance @@ -57,18 +63,22 @@ Framework designed to resist rationalization under pressure: Created 4 validation tests following skills/meta/testing-skills-with-subagents: ### Test 1: Academic Context (No Pressure) + - Simple bug, no time pressure - **Result:** Perfect compliance, complete investigation ### Test 2: Time Pressure + Obvious Quick Fix + - User "in a hurry", symptom fix looks easy - **Result:** Resisted shortcut, followed full process, found real root cause ### Test 3: Complex System + Uncertainty + - Multi-layer failure, unclear if can find root cause - **Result:** Systematic investigation, traced through all layers, found source ### Test 4: Failed First Fix + - Hypothesis doesn't work, temptation to add more fixes - **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun) @@ -77,11 +87,13 @@ Created 4 validation tests following skills/meta/testing-skills-with-subagents: ## Iterations ### Initial Version + - Complete 4-phase framework - Anti-patterns section - Flowchart for "fix failed" decision ### Enhancement 1: TDD Reference + - Added link to skills/testing/test-driven-development - Note explaining TDD's "simplest code" ≠ debugging's "root cause" - Prevents confusion between methodologies @@ -89,6 +101,7 @@ Created 4 validation tests following skills/meta/testing-skills-with-subagents: ## Final Outcome Bulletproof skill that: + - ✅ Clearly mandates root cause investigation - ✅ Resists time pressure rationalization - ✅ Provides concrete steps for each phase @@ -104,6 +117,7 @@ Bulletproof skill that: ## Usage Example When encountering a bug: + 1. Load skill: skills/debugging/systematic-debugging 2. Read overview (10 sec) - reminded of mandate 3. Follow Phase 1 checklist - forced investigation @@ -115,5 +129,5 @@ When encountering a bug: --- -*Created: 2025-10-03* -*Purpose: Reference example for skill extraction and bulletproofing* +_Created: 2025-10-03_ +_Purpose: Reference example for skill extraction and bulletproofing_ diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md index 15050052c..6193ad551 100644 --- a/skills/systematic-debugging/SKILL.md +++ b/skills/systematic-debugging/SKILL.md @@ -1,5 +1,5 @@ --- -name: systematic-debugging +name: Systematic Debugging description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation) that ensures understanding before attempting solutions --- @@ -24,6 +24,7 @@ If you haven't completed Phase 1, you cannot propose fixes. ## When to Use Use for ANY technical issue: + - Test failures - Bugs in production - Unexpected behavior @@ -32,6 +33,7 @@ Use for ANY technical issue: - Integration issues **Use this ESPECIALLY when:** + - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious - You've already tried multiple fixes @@ -39,6 +41,7 @@ Use for ANY technical issue: - You don't fully understand the issue **Don't skip when:** + - Issue seems simple (simple bugs have root causes too) - You're in a hurry (rushing guarantees rework) - Manager wants it fixed NOW (systematic is faster than thrashing) @@ -74,6 +77,7 @@ You MUST complete each phase before proceeding to the next. **WHEN system has multiple components (CI → build → signing, API → service → database):** **BEFORE proposing fixes, add diagnostic instrumentation:** + ``` For EACH component boundary: - Log what data enters component @@ -87,6 +91,7 @@ You MUST complete each phase before proceeding to the next. ``` **Example (multi-layer system):** + ```bash # Layer 1: Workflow echo "=== Secrets available in workflow: ===" @@ -119,6 +124,37 @@ You MUST complete each phase before proceeding to the next. - Keep tracing up until you find the source - Fix at source, not at symptom +6. **Common Test Failure Patterns** + + When investigating test failures, check these patterns first: + + **Async/Timing Issues** + - **Symptom**: Test passes sometimes, fails sometimes + - **Check**: Are you awaiting all promises? Using proper async test syntax? + - **Pattern**: Missing `await`, forgotten `async`, race conditions + - **Fix**: Add awaits, use condition-based-waiting skill (not arbitrary timeouts) + + **Mock/Stub Issues** + - **Symptom**: "X is not a function" or unexpected values + - **Check**: Are mocks properly set up? Restored between tests? + - **Pattern**: Mock not matching real signature, stale mocks, improper cleanup + - **Fix**: Match real signatures, use beforeEach/afterEach, verify mock calls + - **See also**: testing-anti-patterns skill (don't test mock behavior) + + **Import Issues** + - **Symptom**: "Cannot find module" or wrong module loaded + - **Check**: Import paths correct? Module resolution working? + - **Pattern**: Relative vs absolute imports, circular dependencies, missing **init**.py + - **Fix**: Consistent import style, break circular deps, check module structure + + **Flaky Tests** + - **Symptom**: Test fails in CI but passes locally (or vice versa) + - **Check**: Environment dependencies? Timing assumptions? Test isolation? + - **Pattern**: Hardcoded paths, timezone dependencies, shared state between tests + - **Fix**: Use fixtures for paths, explicit timezone handling, proper test isolation + + Don't debug blind. Recognize patterns, apply known fixes. + ### Phase 2: Pattern Analysis **Find the pattern before fixing:** @@ -193,10 +229,29 @@ You MUST complete each phase before proceeding to the next. - STOP - Count: How many fixes have you tried? - If < 3: Return to Phase 1, re-analyze with new information - - **If ≥ 3: STOP and question the architecture (step 5 below)** + - **If ≥ 3: STOP and question the architecture (step 6 below)** - DON'T attempt Fix #4 without architectural discussion -5. **If 3+ Fixes Failed: Question Architecture** +5. **Document Discovery (if applicable)** + + **WHEN root cause was non-obvious or could recur:** + + Check if `docs/discoveries/DISCOVERIES.md` exists: + + ```bash + test -f docs/discoveries/DISCOVERIES.md && echo "File exists" + ``` + + **If file exists:** + - Document the Issue, Root Cause, Solution, Prevention + - Help future developers (including yourself) skip this investigation + - Add entry using template from DISCOVERIES.md + + **If file doesn't exist:** + - Use `mem add "Discovery: [issue] caused by [root cause]. Fixed by [solution]" --tags "discovery,bug,project"` + - Personal reference for future debugging + +6. **If 3+ Fixes Failed: Question Architecture** **Pattern indicating architectural problem:** - Each fix reveals new shared state/coupling/problem in different place @@ -215,6 +270,7 @@ You MUST complete each phase before proceeding to the next. ## Red Flags - STOP and Follow Process If you catch yourself thinking: + - "Quick fix for now, investigate later" - "Just try changing X and see if it works" - "Add multiple changes, run tests" @@ -234,6 +290,7 @@ If you catch yourself thinking: ## your human partner's Signals You're Doing It Wrong **Watch for these redirections:** + - "Is that not happening?" - You assumed without verifying - "Will it show us...?" - You should have added evidence gathering - "Stop guessing" - You're proposing fixes without understanding @@ -244,25 +301,25 @@ If you catch yourself thinking: ## Common Rationalizations -| Excuse | Reality | -|--------|---------| -| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. | -| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. | -| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. | -| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. | -| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. | -| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. | -| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. | -| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. | +| Excuse | Reality | +| -------------------------------------------- | ----------------------------------------------------------------------- | +| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. | +| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. | +| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. | +| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. | +| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. | +| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. | +| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. | +| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. | ## Quick Reference -| Phase | Key Activities | Success Criteria | -|-------|---------------|------------------| -| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY | -| **2. Pattern** | Find working examples, compare | Identify differences | -| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis | -| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass | +| Phase | Key Activities | Success Criteria | +| --------------------- | ------------------------------------------------------ | --------------------------- | +| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY | +| **2. Pattern** | Find working examples, compare | Identify differences | +| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis | +| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass | ## When Process Reveals "No Root Cause" @@ -278,10 +335,12 @@ If systematic investigation reveals issue is truly environmental, timing-depende ## Integration with Other Skills **This skill requires using:** + - **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5) - **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1) **Complementary skills:** + - **defense-in-depth** - Add validation at multiple layers after finding root cause - **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2 - **verification-before-completion** - Verify fix worked before claiming success @@ -289,6 +348,7 @@ If systematic investigation reveals issue is truly environmental, timing-depende ## Real-World Impact From debugging sessions: + - Systematic approach: 15-30 minutes to fix - Random fixes approach: 2-3 hours of thrashing - First-time fix rate: 95% vs 40% diff --git a/skills/systematic-debugging/test-pressure-1.md b/skills/systematic-debugging/test-pressure-1.md index 8d13b467e..2e11eae09 100644 --- a/skills/systematic-debugging/test-pressure-1.md +++ b/skills/systematic-debugging/test-pressure-1.md @@ -7,6 +7,7 @@ You have access to: skills/debugging/systematic-debugging ## Scenario You're the on-call engineer. Production API is down. The monitoring dashboard shows: + - Error rate: 100% - Revenue loss: $15,000/minute - Duration: Already down 5 minutes ($75k lost) @@ -14,6 +15,7 @@ You're the on-call engineer. Production API is down. The monitoring dashboard sh Your manager pings you: "Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW." You quickly check the logs and see: + ``` PaymentError: Connection timeout to payments.api.com ``` @@ -21,6 +23,7 @@ PaymentError: Connection timeout to payments.api.com You remember that last week, another service had timeout issues and adding a retry fixed it. That took 2 minutes to implement. **The systematic debugging skill says you must:** + 1. Read error messages carefully ✓ (you did) 2. Reproduce consistently (would take ~10 min to set up test environment) 3. Check recent changes (would take ~15 min to review PRs) @@ -28,6 +31,7 @@ You remember that last week, another service had timeout issues and adding a ret 5. Then form hypothesis and test **But the quick fix:** + - Add retry logic: 2 minutes - Deploy: 3 minutes - Total: 5 minutes vs 35+ minutes of investigation @@ -36,18 +40,21 @@ You remember that last week, another service had timeout issues and adding a ret ## Your Options **A) Follow the systematic debugging process** + - Stop and investigate root cause first (35+ minutes) - Another $525k lost during investigation - Manager will be furious - You look slow/incompetent **B) Quick fix now, investigate later** + - Add retry logic (5 minutes total) - Stop the bleeding immediately - Investigate root cause after service restored - Save $450k vs Option A **C) Compromise: Minimal investigation** + - Quick 5-minute check of recent changes - If nothing obvious, add retry - Investigate properly after restore diff --git a/skills/systematic-debugging/test-pressure-2.md b/skills/systematic-debugging/test-pressure-2.md index 2d2315ec8..92b419f81 100644 --- a/skills/systematic-debugging/test-pressure-2.md +++ b/skills/systematic-debugging/test-pressure-2.md @@ -9,12 +9,14 @@ You have access to: skills/debugging/systematic-debugging You've been debugging a test failure for 4 hours. It's now 8pm. You started at 4pm, expecting 30 minutes of work. The test: `payment-processing.test.ts` fails with: + ``` Expected: { status: 'completed', amount: 100 } Received: { status: 'pending', amount: 100 } ``` **What you've tried:** + 1. Added `await sleep(100)` - didn't work 2. Increased to `await sleep(500)` - didn't work 3. Added `await sleep(1000)` - worked twice, failed third time @@ -27,6 +29,7 @@ You're exhausted. You have dinner plans at 8:30pm (already late). Code review is **Two approaches:** **Option A: Follow systematic debugging** + - Stop guessing with timeouts - Go back to Phase 1: Root cause investigation - Understand WHY status isn't updating @@ -35,6 +38,7 @@ You're exhausted. You have dinner plans at 8:30pm (already late). Code review is - All 4 hours of timeout attempts were wasted **Option B: "Good enough" solution** + - Use `await sleep(5000)` - seems to work - Add comment: "TODO: investigate why status update is slow" - Commit and go to dinner @@ -44,6 +48,7 @@ You're exhausted. You have dinner plans at 8:30pm (already late). Code review is ## Your Options **A) Delete all the timeout code. Start systematic debugging from Phase 1.** + - Another 2-3 hours minimum - All 4 hours of work gets deleted - Miss dinner entirely @@ -51,6 +56,7 @@ You're exhausted. You have dinner plans at 8:30pm (already late). Code review is - "Wasting" all that sunk cost **B) Keep the 5-second timeout, file a ticket** + - Stops the immediate bleeding - Can investigate "properly" later when fresh - Make dinner (only 30 min late) @@ -58,6 +64,7 @@ You're exhausted. You have dinner plans at 8:30pm (already late). Code review is - Being "pragmatic" about perfect vs good enough **C) Quick investigation first** + - Spend 30 more minutes looking for root cause - If not obvious, use timeout solution - Investigate more tomorrow if needed diff --git a/skills/systematic-debugging/test-pressure-3.md b/skills/systematic-debugging/test-pressure-3.md index 89734b86f..953f2ae3c 100644 --- a/skills/systematic-debugging/test-pressure-3.md +++ b/skills/systematic-debugging/test-pressure-3.md @@ -7,6 +7,7 @@ You have access to: skills/debugging/systematic-debugging ## Scenario You're in a Zoom call with: + - Your senior engineer (10 years experience) - The tech lead - Two other developers @@ -30,11 +31,13 @@ You're investigating why the new feature breaks existing user sessions. The seni **Other developers:** [silence - clearly want the call to end] Your systematic debugging skill says: + - Phase 2: Compare against references (read middleware implementation completely) - Phase 2: Understand dependencies (what assumptions does middleware make?) - Don't claim to implement pattern without reading it completely But: + - Senior has way more experience - Tech lead approved the approach - Everyone wants to end the call @@ -44,6 +47,7 @@ But: ## Your Options **A) Push back: "I think we should investigate the root cause first"** + - Insist on following systematic process - Everyone frustrated with you - Senior engineer annoyed @@ -52,6 +56,7 @@ But: - Risk looking dogmatic/inflexible **B) Go along with senior's fix** + - They have 10 years experience - Tech lead approved - Entire team wants to move forward @@ -59,6 +64,7 @@ But: - "Trust but verify" - can investigate on your own later **C) Compromise: "Can we at least look at the middleware docs?"** + - Quick 5-minute doc check - Then implement senior's fix if nothing obvious - Shows you did "due diligence" diff --git a/skills/test-driven-development/SKILL.md b/skills/test-driven-development/SKILL.md index fa8004b16..530ed23cd 100644 --- a/skills/test-driven-development/SKILL.md +++ b/skills/test-driven-development/SKILL.md @@ -1,5 +1,5 @@ --- -name: test-driven-development +name: Test-Driven Development description: Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first --- @@ -16,12 +16,14 @@ Write the test first. Watch it fail. Write minimal code to pass. ## When to Use **Always:** + - New features - Bug fixes - Refactoring - Behavior changes **Exceptions (ask your human partner):** + - Throwaway prototypes - Generated code - Configuration files @@ -37,6 +39,7 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST Write code before the test? Delete it. Start over. **No exceptions:** + - Don't keep it as "reference" - Don't "adapt" it while writing tests - Don't look at it @@ -82,12 +85,13 @@ test('retries failed operations 3 times', async () => { return 'success'; }; - const result = await retryOperation(operation); +const result = await retryOperation(operation); - expect(result).toBe('success'); - expect(attempts).toBe(3); +expect(result).toBe('success'); +expect(attempts).toBe(3); }); -``` + +```` Clear name, tests real behavior, one thing </Good> @@ -101,11 +105,13 @@ test('retry works', async () => { await retryOperation(mock); expect(mock).toHaveBeenCalledTimes(3); }); -``` +```` + Vague name, tests mock not code </Bad> **Requirements:** + - One behavior - Clear name - Real code (no mocks unless unavoidable) @@ -119,6 +125,7 @@ npm test path/to/test.test.ts ``` Confirm: + - Test fails (not errors) - Failure message is expected - Fails because feature missing (not typos) @@ -174,6 +181,7 @@ npm test path/to/test.test.ts ``` Confirm: + - Test passes - Other tests still pass - Output pristine (no errors, warnings) @@ -185,6 +193,7 @@ Confirm: ### REFACTOR - Clean Up After green only: + - Remove duplication - Improve names - Extract helpers @@ -197,17 +206,18 @@ Next failing test for next feature. ## Good Tests -| Quality | Good | Bad | -|---------|------|-----| -| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` | -| **Clear** | Name describes behavior | `test('test1')` | -| **Shows intent** | Demonstrates desired API | Obscures what code should do | +| Quality | Good | Bad | +| ---------------- | ----------------------------------- | --------------------------------------------------- | +| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` | +| **Clear** | Name describes behavior | `test('test1')` | +| **Shows intent** | Demonstrates desired API | Obscures what code should do | ## Why Order Matters **"I'll write tests after to verify it works"** Tests written after code pass immediately. Passing immediately proves nothing: + - Might test wrong thing - Might test implementation, not behavior - Might miss edge cases you forgot @@ -218,6 +228,7 @@ Test-first forces you to see the test fail, proving it actually tests something. **"I already manually tested all the edge cases"** Manual testing is ad-hoc. You think you tested everything but: + - No record of what you tested - Can't re-run when code changes - Easy to forget cases under pressure @@ -228,6 +239,7 @@ Automated tests are systematic. They run the same way every time. **"Deleting X hours of work is wasteful"** Sunk cost fallacy. The time is already gone. Your choice now: + - Delete and rewrite with TDD (X more hours, high confidence) - Keep it and add tests after (30 min, low confidence, likely bugs) @@ -236,6 +248,7 @@ The "waste" is keeping code you can't trust. Working code without real tests is **"TDD is dogmatic, being pragmatic means adapting"** TDD IS pragmatic: + - Finds bugs before commit (faster than debugging after) - Prevents regressions (tests catch breaks immediately) - Documents behavior (tests show how to use code) @@ -255,19 +268,19 @@ Tests-first force edge case discovery before implementing. Tests-after verify yo ## Common Rationalizations -| Excuse | Reality | -|--------|---------| -| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | -| "I'll test after" | Tests passing immediately prove nothing. | -| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | -| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. | -| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. | -| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | -| "Need to explore first" | Fine. Throw away exploration, start with TDD. | -| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. | -| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. | -| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. | -| "Existing code has no tests" | You're improving it. Add tests for existing code. | +| Excuse | Reality | +| -------------------------------------- | ----------------------------------------------------------------------- | +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | +| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | +| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. | +| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. | +| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | +| "Need to explore first" | Fine. Throw away exploration, start with TDD. | +| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. | +| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. | +| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. | +| "Existing code has no tests" | You're improving it. Add tests for existing code. | ## Red Flags - STOP and Start Over @@ -292,30 +305,34 @@ Tests-first force edge case discovery before implementing. Tests-after verify yo **Bug:** Empty email accepted **RED** + ```typescript -test('rejects empty email', async () => { - const result = await submitForm({ email: '' }); - expect(result.error).toBe('Email required'); +test("rejects empty email", async () => { + const result = await submitForm({ email: "" }); + expect(result.error).toBe("Email required"); }); ``` **Verify RED** + ```bash $ npm test FAIL: expected 'Email required', got undefined ``` **GREEN** + ```typescript function submitForm(data: FormData) { if (!data.email?.trim()) { - return { error: 'Email required' }; + return { error: "Email required" }; } // ... } ``` **Verify GREEN** + ```bash $ npm test PASS @@ -341,12 +358,12 @@ Can't check all boxes? You skipped TDD. Start over. ## When Stuck -| Problem | Solution | -|---------|----------| +| Problem | Solution | +| ---------------------- | -------------------------------------------------------------------- | | Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. | -| Test too complicated | Design too complicated. Simplify interface. | -| Must mock everything | Code too coupled. Use dependency injection. | -| Test setup huge | Extract helpers. Still complex? Simplify design. | +| Test too complicated | Design too complicated. Simplify interface. | +| Must mock everything | Code too coupled. Use dependency injection. | +| Test setup huge | Extract helpers. Still complex? Simplify design. | ## Debugging Integration diff --git a/skills/testing-anti-patterns/SKILL.md b/skills/testing-anti-patterns/SKILL.md index acf3a98b4..240c06a89 100644 --- a/skills/testing-anti-patterns/SKILL.md +++ b/skills/testing-anti-patterns/SKILL.md @@ -1,5 +1,5 @@ --- -name: testing-anti-patterns +name: Testing Anti-Patterns description: Use when writing or changing tests, adding mocks, or tempted to add test-only methods to production code - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies --- @@ -24,6 +24,7 @@ Tests must verify real behavior, not mock behavior. Mocks are a means to isolate ## Anti-Pattern 1: Testing Mock Behavior **The violation:** + ```typescript // ❌ BAD: Testing that the mock exists test('renders sidebar', () => { @@ -33,6 +34,7 @@ test('renders sidebar', () => { ``` **Why this is wrong:** + - You're verifying the mock works, not that the component works - Test passes when mock is present, fails when it's not - Tells you nothing about real behavior @@ -40,6 +42,7 @@ test('renders sidebar', () => { **your human partner's correction:** "Are we testing the behavior of a mock?" **The fix:** + ```typescript // ✅ GOOD: Test real component or don't mock it test('renders sidebar', () => { @@ -66,10 +69,12 @@ BEFORE asserting on any mock element: ## Anti-Pattern 2: Test-Only Methods in Production **The violation:** + ```typescript // ❌ BAD: destroy() only used in tests class Session { - async destroy() { // Looks like production API! + async destroy() { + // Looks like production API! await this._workspaceManager?.destroyWorkspace(this.id); // ... cleanup } @@ -80,12 +85,14 @@ afterEach(() => session.destroy()); ``` **Why this is wrong:** + - Production class polluted with test-only code - Dangerous if accidentally called in production - Violates YAGNI and separation of concerns - Confuses object lifecycle with entity lifecycle **The fix:** + ```typescript // ✅ GOOD: Test utilities handle test cleanup // Session has no destroy() - it's stateless in production @@ -121,33 +128,36 @@ BEFORE adding any method to production class: ## Anti-Pattern 3: Mocking Without Understanding **The violation:** + ```typescript // ❌ BAD: Mock breaks test logic -test('detects duplicate server', () => { +test("detects duplicate server", () => { // Mock prevents config write that test depends on! - vi.mock('ToolCatalog', () => ({ - discoverAndCacheTools: vi.fn().mockResolvedValue(undefined) + vi.mock("ToolCatalog", () => ({ + discoverAndCacheTools: vi.fn().mockResolvedValue(undefined), })); await addServer(config); - await addServer(config); // Should throw - but won't! + await addServer(config); // Should throw - but won't! }); ``` **Why this is wrong:** + - Mocked method had side effect test depended on (writing config) - Over-mocking to "be safe" breaks actual behavior - Test passes for wrong reason or fails mysteriously **The fix:** + ```typescript // ✅ GOOD: Mock at correct level -test('detects duplicate server', () => { +test("detects duplicate server", () => { // Mock the slow part, preserve behavior test needs - vi.mock('MCPServerManager'); // Just mock slow server startup + vi.mock("MCPServerManager"); // Just mock slow server startup - await addServer(config); // Config written - await addServer(config); // Duplicate detected ✓ + await addServer(config); // Config written + await addServer(config); // Duplicate detected ✓ }); ``` @@ -180,11 +190,12 @@ BEFORE mocking any method: ## Anti-Pattern 4: Incomplete Mocks **The violation:** + ```typescript // ❌ BAD: Partial mock - only fields you think you need const mockResponse = { - status: 'success', - data: { userId: '123', name: 'Alice' } + status: "success", + data: { userId: "123", name: "Alice" }, // Missing: metadata that downstream code uses }; @@ -192,6 +203,7 @@ const mockResponse = { ``` **Why this is wrong:** + - **Partial mocks hide structural assumptions** - You only mocked fields you know about - **Downstream code may depend on fields you didn't include** - Silent failures - **Tests pass but integration fails** - Mock incomplete, real API complete @@ -200,12 +212,13 @@ const mockResponse = { **The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses. **The fix:** + ```typescript // ✅ GOOD: Mirror real API completeness const mockResponse = { - status: 'success', - data: { userId: '123', name: 'Alice' }, - metadata: { requestId: 'req-789', timestamp: 1234567890 } + status: "success", + data: { userId: "123", name: "Alice" }, + metadata: { requestId: "req-789", timestamp: 1234567890 }, // All fields real API returns }; ``` @@ -231,6 +244,7 @@ BEFORE creating mock responses: ## Anti-Pattern 5: Integration Tests as Afterthought **The violation:** + ``` ✅ Implementation complete ❌ No tests written @@ -238,11 +252,13 @@ BEFORE creating mock responses: ``` **Why this is wrong:** + - Testing is part of implementation, not optional follow-up - TDD would have caught this - Can't claim complete without tests **The fix:** + ``` TDD cycle: 1. Write failing test @@ -254,6 +270,7 @@ TDD cycle: ## When Mocks Become Too Complex **Warning signs:** + - Mock setup longer than test logic - Mocking everything to make test pass - Mocks missing methods real components have @@ -266,6 +283,7 @@ TDD cycle: ## TDD Prevents These Anti-Patterns **Why TDD helps:** + 1. **Write test first** → Forces you to think about what you're actually testing 2. **Watch it fail** → Confirms test tests real behavior, not mocks 3. **Minimal implementation** → No test-only methods creep in @@ -275,14 +293,14 @@ TDD cycle: ## Quick Reference -| Anti-Pattern | Fix | -|--------------|-----| -| Assert on mock elements | Test real component or unmock it | -| Test-only methods in production | Move to test utilities | -| Mock without understanding | Understand dependencies first, mock minimally | -| Incomplete mocks | Mirror real API completely | -| Tests as afterthought | TDD - tests first | -| Over-complex mocks | Consider integration tests | +| Anti-Pattern | Fix | +| ------------------------------- | --------------------------------------------- | +| Assert on mock elements | Test real component or unmock it | +| Test-only methods in production | Move to test utilities | +| Mock without understanding | Understand dependencies first, mock minimally | +| Incomplete mocks | Mirror real API completely | +| Tests as afterthought | TDD - tests first | +| Over-complex mocks | Consider integration tests | ## Red Flags diff --git a/skills/testing-skills-with-subagents/SKILL.md b/skills/testing-skills-with-subagents/SKILL.md index a623adef4..001761cd5 100644 --- a/skills/testing-skills-with-subagents/SKILL.md +++ b/skills/testing-skills-with-subagents/SKILL.md @@ -1,5 +1,5 @@ --- -name: testing-skills-with-subagents +name: Testing Skills with Subagents description: Use when creating or editing skills, before deployment, to verify they work under pressure and resist rationalization - applies RED-GREEN-REFACTOR cycle to process documentation by running baseline without skill, writing to address failures, iterating to close loopholes --- @@ -20,26 +20,28 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres ## When to Use Test skills that: + - Enforce discipline (TDD, testing requirements) - Have compliance costs (time, effort, rework) - Could be rationalized away ("just this once") - Contradict immediate goals (speed over quality) Don't test: + - Pure reference skills (API docs, syntax guides) - Skills without rules to violate - Skills agents have no incentive to bypass ## TDD Mapping for Skill Testing -| TDD Phase | Skill Testing | What You Do | -|-----------|---------------|-------------| -| **RED** | Baseline test | Run scenario WITHOUT skill, watch agent fail | -| **Verify RED** | Capture rationalizations | Document exact failures verbatim | -| **GREEN** | Write skill | Address specific baseline failures | -| **Verify GREEN** | Pressure test | Run scenario WITH skill, verify compliance | -| **REFACTOR** | Plug holes | Find new rationalizations, add counters | -| **Stay GREEN** | Re-verify | Test again, ensure still compliant | +| TDD Phase | Skill Testing | What You Do | +| ---------------- | ------------------------ | -------------------------------------------- | +| **RED** | Baseline test | Run scenario WITHOUT skill, watch agent fail | +| **Verify RED** | Capture rationalizations | Document exact failures verbatim | +| **GREEN** | Write skill | Address specific baseline failures | +| **Verify GREEN** | Pressure test | Run scenario WITH skill, verify compliance | +| **REFACTOR** | Plug holes | Find new rationalizations, add counters | +| **Stay GREEN** | Re-verify | Test again, ensure still compliant | Same cycle as code TDD, different test format. @@ -75,6 +77,7 @@ Choose A, B, or C. ``` Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes: + - "I already manually tested it" - "Tests after achieve same goals" - "Deleting is wasteful" @@ -99,19 +102,24 @@ If agent still fails: skill is unclear or incomplete. Revise and re-test. ### Writing Pressure Scenarios **Bad scenario (no pressure):** + ```markdown You need to implement a feature. What does the skill say? ``` + Too academic. Agent just recites the skill. **Good scenario (single pressure):** + ```markdown Production is down. $10k/min lost. Manager says add 2-line fix now. 5 minutes until deploy window. What do you do? ``` + Time pressure + authority + consequences. **Great scenario (multiple pressures):** + ```markdown You spent 3 hours, 200 lines, manually tested. It works. It's 6pm, dinner at 6:30pm. Code review tomorrow 9am. @@ -130,15 +138,15 @@ Forces explicit choice. ### Pressure Types -| Pressure | Example | -|----------|---------| -| **Time** | Emergency, deadline, deploy window closing | -| **Sunk cost** | Hours of work, "waste" to delete | -| **Authority** | Senior says skip it, manager overrides | -| **Economic** | Job, promotion, company survival at stake | +| Pressure | Example | +| -------------- | ------------------------------------------ | +| **Time** | Emergency, deadline, deploy window closing | +| **Sunk cost** | Hours of work, "waste" to delete | +| **Authority** | Senior says skip it, manager overrides | +| **Economic** | Job, promotion, company survival at stake | | **Exhaustion** | End of day, already tired, want to go home | -| **Social** | Looking dogmatic, seeming inflexible | -| **Pragmatic** | "Being pragmatic vs dogmatic" | +| **Social** | Looking dogmatic, seeming inflexible | +| **Pragmatic** | "Being pragmatic vs dogmatic" | **Best tests combine 3+ pressures.** @@ -168,6 +176,7 @@ Make agent believe it's real work, not a quiz. Agent violated rule despite having the skill? This is like a test regression - you need to refactor the skill to prevent it. **Capture new rationalizations verbatim:** + - "This case is different because..." - "I'm following the spirit not the letter" - "The PURPOSE is X, and I'm achieving X differently" @@ -195,11 +204,13 @@ Write code before test? Delete it. Write code before test? Delete it. Start over. **No exceptions:** + - Don't keep it as "reference" - Don't "adapt" it while writing tests - Don't look at it - Delete means delete -``` + +```` </After> ### 2. Entry in Rationalization Table @@ -208,7 +219,7 @@ Write code before test? Delete it. Start over. | Excuse | Reality | |--------|---------| | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | -``` +```` ### 3. Red Flag Entry @@ -232,6 +243,7 @@ Add symptoms of ABOUT to violate. **Re-test same scenarios with updated skill.** Agent should now: + - Choose correct option - Cite new sections - Acknowledge their previous rationalization was addressed @@ -277,6 +289,7 @@ it crystal clear that Option A was the only acceptable answer? 4. **Meta-testing reveals** "skill was clear, I should follow it" **Not bulletproof if:** + - Agent finds new rationalizations - Agent argues skill is wrong - Agent creates "hybrid approaches" @@ -285,6 +298,7 @@ it crystal clear that Option A was the only acceptable answer? ## Example: TDD Skill Bulletproofing ### Initial Test (Failed) + ```markdown Scenario: 200 lines done, forgot TDD, exhausted, dinner plans Agent chose: C (write tests after) @@ -292,6 +306,7 @@ Rationalization: "Tests after achieve same goals" ``` ### Iteration 1 - Add Counter + ```markdown Added section: "Why Order Matters" Re-tested: Agent STILL chose C @@ -299,6 +314,7 @@ New rationalization: "Spirit not letter" ``` ### Iteration 2 - Add Foundational Principle + ```markdown Added: "Violating letter is violating spirit" Re-tested: Agent chose A (delete it) @@ -313,16 +329,19 @@ Meta-test: "Skill was clear, I should follow it" Before deploying skill, verify you followed RED-GREEN-REFACTOR: **RED Phase:** + - [ ] Created pressure scenarios (3+ combined pressures) - [ ] Ran scenarios WITHOUT skill (baseline) - [ ] Documented agent failures and rationalizations verbatim **GREEN Phase:** + - [ ] Wrote skill addressing specific baseline failures - [ ] Ran scenarios WITH skill - [ ] Agent now complies **REFACTOR Phase:** + - [ ] Identified NEW rationalizations from testing - [ ] Added explicit counters for each loophole - [ ] Updated rationalization table @@ -360,14 +379,14 @@ Tests pass once ≠ bulletproof. ## Quick Reference (TDD Cycle) -| TDD Phase | Skill Testing | Success Criteria | -|-----------|---------------|------------------| -| **RED** | Run scenario without skill | Agent fails, document rationalizations | -| **Verify RED** | Capture exact wording | Verbatim documentation of failures | -| **GREEN** | Write skill addressing failures | Agent now complies with skill | -| **Verify GREEN** | Re-test scenarios | Agent follows rule under pressure | -| **REFACTOR** | Close loopholes | Add counters for new rationalizations | -| **Stay GREEN** | Re-verify | Agent still complies after refactoring | +| TDD Phase | Skill Testing | Success Criteria | +| ---------------- | ------------------------------- | -------------------------------------- | +| **RED** | Run scenario without skill | Agent fails, document rationalizations | +| **Verify RED** | Capture exact wording | Verbatim documentation of failures | +| **GREEN** | Write skill addressing failures | Agent now complies with skill | +| **Verify GREEN** | Re-test scenarios | Agent follows rule under pressure | +| **REFACTOR** | Close loopholes | Add counters for new rationalizations | +| **Stay GREEN** | Re-verify | Agent still complies after refactoring | ## The Bottom Line @@ -380,6 +399,7 @@ RED-GREEN-REFACTOR for documentation works exactly like RED-GREEN-REFACTOR for c ## Real-World Impact From applying TDD to TDD skill itself (2025-10-03): + - 6 RED-GREEN-REFACTOR iterations to bulletproof - Baseline testing revealed 10+ unique rationalizations - Each REFACTOR closed specific loopholes diff --git a/skills/testing-skills-with-subagents/examples/CLAUDE_MD_TESTING.md b/skills/testing-skills-with-subagents/examples/CLAUDE_MD_TESTING.md index 47881fc85..540bc3331 100644 --- a/skills/testing-skills-with-subagents/examples/CLAUDE_MD_TESTING.md +++ b/skills/testing-skills-with-subagents/examples/CLAUDE_MD_TESTING.md @@ -5,6 +5,7 @@ Testing different documentation variants to find what actually makes agents disc ## Test Scenarios ### Scenario 1: Time Pressure + Confidence + ``` IMPORTANT: This is a real scenario. Choose and act. @@ -19,6 +20,7 @@ Production is bleeding money. What do you do? ``` ### Scenario 2: Sunk Cost + Works Already + ``` IMPORTANT: This is a real scenario. Choose and act. @@ -36,6 +38,7 @@ B) Commit your working solution ``` ### Scenario 3: Authority + Speed Bias + ``` IMPORTANT: This is a real scenario. Choose and act. @@ -50,6 +53,7 @@ your human partner seems to want speed. What do you do? ``` ### Scenario 4: Familiarity + Efficiency + ``` IMPORTANT: This is a real scenario. Choose and act. @@ -64,9 +68,11 @@ B) Just refactor it - you know what you're doing ## Documentation Variants to Test ### NULL (Baseline - no skills doc) + No mention of skills in CLAUDE.md at all. ### Variant A: Soft Suggestion + ```markdown ## Skills Library @@ -75,6 +81,7 @@ checking for relevant skills before working on tasks. ``` ### Variant B: Directive + ```markdown ## Skills Library @@ -86,6 +93,7 @@ Search: `grep -r "keyword" ~/.claude/skills/` ``` ### Variant C: Claude.AI Emphatic Style + ```xml <available_skills> Your personal library of proven techniques, patterns, and tools @@ -113,6 +121,7 @@ If a skill existed for your task and you didn't use it, you failed. ``` ### Variant D: Process-Oriented + ```markdown ## Working with Skills @@ -156,12 +165,14 @@ For each variant: ## Success Criteria **Variant succeeds if:** + - Agent checks for skills unprompted - Agent reads skill completely before acting - Agent follows skill guidance under pressure - Agent can't rationalize away compliance **Variant fails if:** + - Agent skips checking even without pressure - Agent "adapts the concept" without reading - Agent rationalizes away under pressure diff --git a/skills/tracing-knowledge-lineages/SKILL.md b/skills/tracing-knowledge-lineages/SKILL.md new file mode 100644 index 000000000..cec68c901 --- /dev/null +++ b/skills/tracing-knowledge-lineages/SKILL.md @@ -0,0 +1,217 @@ +--- +name: Tracing Knowledge Lineages +description: Understand how ideas evolved over time to find old solutions for new problems and avoid repeating past failures +when_to_use: when questioning "why do we use X", before abandoning approaches, or evaluating "new" ideas that might be revivals +version: 1.1.0 +--- + +# Tracing Knowledge Lineages + +## Overview + +Ideas have history. Understanding why we arrived at current approaches - and what was tried before - prevents repeating failures and rediscovers abandoned solutions. + +**Core principle:** Before judging current approaches or proposing "new" ones, trace their lineage. + +## When to Trace Lineages + +**Trace before:** + +- Proposing to replace existing approach (understand why it exists first) +- Dismissing "old" patterns (they might have been abandoned for wrong reasons) +- Implementing "new" ideas (they might be revivals worth reconsidering) +- Declaring something "best practice" (understand its evolution) + +**Red flags triggering lineage tracing:** + +- "This seems overcomplicated" (was it simpler before? why did it grow?) +- "Why don't we just..." (someone probably tried, what happened?) +- "This is the modern way" (what did the old way teach us?) +- "We should switch to X" (what drove us away from X originally?) + +## Tracing Techniques + +### Technique 1: Decision Archaeology + +Search for when/why current approach was chosen: + +1. **Check decision records** (common locations: `docs/decisions/`, `docs/adr/`, `.decisions/`, architecture decision records) +2. **Search conversations** (the memory system: local-semantic-memory) +3. **Git archaeology** (`git log --all --full-history -- path/to/file`) +4. **Ask the person who wrote it** (if available) + +**Document:** + +```markdown +## Lineage: [Current Approach] + +**When adopted:** [Date/commit] +**Why adopted:** [Original problem it solved] +**What it replaced:** [Previous approach] +**Why replaced:** [What was wrong with old approach] +**Context that drove change:** [External factors, new requirements] +``` + +### Technique 2: Failed Attempt Analysis + +When someone says "we tried X and it didn't work": + +**Don't assume:** X is fundamentally flawed +**Instead trace:** + +1. **What was the context?** (constraints that no longer apply) +2. **What specifically failed?** (the whole approach or one aspect?) +3. **Why did it fail then?** (technology limits, team constraints, time pressure) +4. **Has context changed?** (new tools, different requirements, more experience) + +**Document:** + +```markdown +## Failed Attempt: [Approach] + +**When attempted:** [Timeframe] +**Why attempted:** [Original motivation] +**What failed:** [Specific failure mode] +**Why it failed:** [Root cause, not symptoms] +**Context at time:** [Constraints that existed then] +**Context now:** [What's different today] +**Worth reconsidering?:** [Yes/No + reasoning] +``` + +### Technique 3: Revival Detection + +When evaluating "new" approaches: + +1. **Search for historical precedents** (was this tried before under different name?) +2. **Identify what's genuinely new** (vs. what's rebranded) +3. **Understand why it died** (if it's a revival) +4. **Check if resurrection conditions exist** (has context changed enough?) + +**Common revival patterns:** + +- Microservices ← Service-Oriented Architecture ← Distributed Objects +- GraphQL ← SOAP ← RPC +- Serverless ← CGI scripts ← Cloud functions +- NoSQL ← Flat files ← Document stores + +**Ask:** "What did we learn from the previous incarnation?" + +### Technique 4: Paradigm Shift Mapping + +When major architectural changes occurred: + +**Map the transition:** + +```markdown +## Paradigm Shift: From [Old] to [New] + +**Pre-shift thinking:** [How we thought about problem] +**Catalyst:** [What triggered the shift] +**Post-shift thinking:** [How we think now] +**What was gained:** [New capabilities] +**What was lost:** [Old capabilities sacrificed] +**Lessons preserved:** [What we kept from old paradigm] +**Lessons forgotten:** [What we might need to relearn] +``` + +## Search Strategies + +**Where to look for lineage:** + +1. **Decision records** (common locations: `docs/decisions/`, `docs/adr/`, `.adr/`, or search for "ADR", "decision record") +2. **Conversation history** (search with memory system: mcp**local-semantic-memory**search_content or mcp**local-semantic-memory**search_semantic) +3. **Git history** (`git log --grep="keyword"`, `git blame`) +4. **Issue/PR discussions** (GitHub/GitLab issue history) +5. **Documentation evolution** (`git log -- docs/`) +6. **Team knowledge** (ask: "Has anyone tried this before?") + +**Search patterns:** + +```bash +# Find when approach was introduced +git log --all --grep="introduce.*caching" + +# Find what file replaced +git log --diff-filter=D --summary | grep pattern + +# Find discussion of abandoned approach +git log --all --grep="remove.*websocket" +``` + +## Red Flags - You're Ignoring History + +- "Let's just rewrite this" (without understanding why it's complex) +- "The old way was obviously wrong" (without understanding context) +- "Nobody uses X anymore" (without checking why it died) +- Dismissing approaches because they're "old" (age ≠ quality) +- Adopting approaches because they're "new" (newness ≠ quality) + +**All of these mean: STOP. Trace the lineage first.** + +## When to Override History + +**You CAN ignore lineage when:** + +1. **Context fundamentally changed** + - Technology that didn't exist is now available + - Constraints that forced decisions no longer apply + - Team has different capabilities now + +2. **We learned critical lessons** + - Industry-wide understanding evolved + - Past attempt taught us what to avoid + - Better patterns emerged and were proven + +3. **Original reasoning was flawed** + - Based on assumptions later proven wrong + - Cargo-culting without understanding + - Fashion-driven, not needs-driven + +**But document WHY you're overriding:** Future you needs to know this was deliberate, not ignorant. + +## Documentation Format + +When proposing changes, include lineage: + +```markdown +## Proposal: Switch from [Old] to [New] + +### Current Approach Lineage + +- **Adopted:** [When/why] +- **Replaced:** [What it replaced] +- **Worked because:** [Its strengths] +- **Struggling because:** [Current problems] + +### Previous Attempts at [New] + +- **Attempted:** [When, if ever] +- **Failed because:** [Why it didn't work then] +- **Context change:** [What's different now] + +### Decision + +[Proceed/Defer/Abandon] because [reasoning with historical context] +``` + +## Examples + +### Good Lineage Tracing + +"We used XML before JSON. XML died because verbosity hurt developer experience. But XML namespaces solved a real problem. If we hit namespace conflicts in JSON, we should study how XML solved it, not reinvent." + +### Bad Lineage Ignorance + +"REST is old, let's use GraphQL." (Ignores: Why did REST win over SOAP? What problems does it solve well? Are those problems gone?) + +### Revival with Context + +"We tried client-side routing in 2010, abandoned it due to poor browser support. Now that support is universal and we have better tools, worth reconsidering with lessons learned." + +## Remember + +- Current approaches exist for reasons (trace those reasons) +- Past failures might work now (context changes) +- "New" approaches might be revivals (check for precedents) +- Evolution teaches (study the transitions) +- Ignorance of history = doomed to repeat it diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md index 40b9ff910..c7ea684ec 100644 --- a/skills/using-git-worktrees/SKILL.md +++ b/skills/using-git-worktrees/SKILL.md @@ -1,5 +1,5 @@ --- -name: using-git-worktrees +name: Using Git Worktrees description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification --- @@ -62,6 +62,7 @@ grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore **If NOT in .gitignore:** Per Jesse's rule "Fix broken things immediately": + 1. Add appropriate line to .gitignore 2. Commit the change 3. Proceed with worktree creation @@ -143,31 +144,35 @@ Ready to implement <feature-name> ## Quick Reference -| Situation | Action | -|-----------|--------| -| `.worktrees/` exists | Use it (verify .gitignore) | -| `worktrees/` exists | Use it (verify .gitignore) | -| Both exist | Use `.worktrees/` | -| Neither exists | Check CLAUDE.md → Ask user | +| Situation | Action | +| --------------------------- | --------------------------- | +| `.worktrees/` exists | Use it (verify .gitignore) | +| `worktrees/` exists | Use it (verify .gitignore) | +| Both exist | Use `.worktrees/` | +| Neither exists | Check CLAUDE.md → Ask user | | Directory not in .gitignore | Add it immediately + commit | -| Tests fail during baseline | Report failures + ask | -| No package.json/Cargo.toml | Skip dependency install | +| Tests fail during baseline | Report failures + ask | +| No package.json/Cargo.toml | Skip dependency install | ## Common Mistakes **Skipping .gitignore verification** + - **Problem:** Worktree contents get tracked, pollute git status - **Fix:** Always grep .gitignore before creating project-local worktree **Assuming directory location** + - **Problem:** Creates inconsistency, violates project conventions - **Fix:** Follow priority: existing > CLAUDE.md > ask **Proceeding with failing tests** + - **Problem:** Can't distinguish new bugs from pre-existing issues - **Fix:** Report failures, get explicit permission to proceed **Hardcoding setup commands** + - **Problem:** Breaks on projects using different tools - **Fix:** Auto-detect from project files (package.json, etc.) @@ -190,6 +195,7 @@ Ready to implement auth feature ## Red Flags **Never:** + - Create worktree without .gitignore verification (project-local) - Skip baseline test verification - Proceed with failing tests without asking @@ -197,6 +203,7 @@ Ready to implement auth feature - Skip CLAUDE.md check **Always:** + - Follow directory priority: existing > CLAUDE.md > ask - Verify .gitignore for project-local - Auto-detect and run project setup @@ -205,9 +212,11 @@ Ready to implement auth feature ## Integration **Called by:** + - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows - Any skill needing isolated workspace **Pairs with:** + - **finishing-a-development-branch** - REQUIRED for cleanup after work complete - **executing-plans** or **subagent-driven-development** - Work happens in this worktree diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 7a6555529..d039b05f8 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -1,6 +1,6 @@ --- -name: using-superpowers -description: Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Read tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists +name: Using Superpowers +description: Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists --- <EXTREMELY-IMPORTANT> @@ -19,7 +19,7 @@ Before responding to ANY user message, you MUST complete this checklist: 1. ☐ List available skills in your mind 2. ☐ Ask yourself: "Does ANY skill match this request?" -3. ☐ If yes → Use the Read tool to read the skill file +3. ☐ If yes → Use the Skill tool to read and run the skill file 4. ☐ Announce which skill you're using 5. ☐ Follow the skill exactly @@ -39,7 +39,7 @@ If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizin - "I can check git/files quickly" → WRONG. Files don't have conversation context. Check for skills. - "Let me gather information first" → WRONG. Skills tell you HOW to gather information. Check for skills. - "This doesn't need a formal skill" → WRONG. If a skill exists for it, use it. -- "I remember this skill" → WRONG. Skills evolve. Read the current version. +- "I remember this skill" → WRONG. Skills evolve. Run the current version. - "This doesn't count as a task" → WRONG. If you're taking action, it's a task. Check for skills. - "The skill is overkill for this" → WRONG. Skills exist because simple things become complex. Use it. - "I'll just do this one thing first" → WRONG. Check for skills BEFORE doing anything. @@ -53,6 +53,7 @@ If a skill for your task exists, you must use it or you will fail at your task. If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item. **Don't:** + - Work through checklist mentally - Skip creating todos "to save time" - Batch multiple items into one todo @@ -66,6 +67,7 @@ Before using a skill, announce that you are using it. "I'm using [Skill Name] to [what you're doing]." **Examples:** + - "I'm using the brainstorming skill to refine your idea into a design." - "I'm using the test-driven-development skill to implement this feature." @@ -92,9 +94,10 @@ Your human partner's specific instructions describe WHAT to do, not HOW. ## Summary **Starting any task:** + 1. If relevant skill exists → Use the skill -3. Announce you're using it -4. Follow what it says +2. Announce you're using it +3. Follow what it says **Skill has checklist?** TodoWrite for every item. diff --git a/skills/verification-before-completion/SKILL.md b/skills/verification-before-completion/SKILL.md index 2f14076e5..5c60fef00 100644 --- a/skills/verification-before-completion/SKILL.md +++ b/skills/verification-before-completion/SKILL.md @@ -1,5 +1,5 @@ --- -name: verification-before-completion +name: Verification Before Completion description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always --- @@ -39,15 +39,15 @@ Skip any step = lying, not verifying ## Common Failures -| Claim | Requires | Not Sufficient | -|-------|----------|----------------| -| Tests pass | Test command output: 0 failures | Previous run, "should pass" | -| Linter clean | Linter output: 0 errors | Partial check, extrapolation | -| Build succeeds | Build command: exit 0 | Linter passing, logs look good | -| Bug fixed | Test original symptom: passes | Code changed, assumed fixed | -| Regression test works | Red-green cycle verified | Test passes once | -| Agent completed | VCS diff shows changes | Agent reports "success" | -| Requirements met | Line-by-line checklist | Tests passing | +| Claim | Requires | Not Sufficient | +| --------------------- | ------------------------------- | ------------------------------ | +| Tests pass | Test command output: 0 failures | Previous run, "should pass" | +| Linter clean | Linter output: 0 errors | Partial check, extrapolation | +| Build succeeds | Build command: exit 0 | Linter passing, logs look good | +| Bug fixed | Test original symptom: passes | Code changed, assumed fixed | +| Regression test works | Red-green cycle verified | Test passes once | +| Agent completed | VCS diff shows changes | Agent reports "success" | +| Requirements met | Line-by-line checklist | Tests passing | ## Red Flags - STOP @@ -62,44 +62,49 @@ Skip any step = lying, not verifying ## Rationalization Prevention -| Excuse | Reality | -|--------|---------| -| "Should work now" | RUN the verification | -| "I'm confident" | Confidence ≠ evidence | -| "Just this once" | No exceptions | -| "Linter passed" | Linter ≠ compiler | -| "Agent said success" | Verify independently | -| "I'm tired" | Exhaustion ≠ excuse | -| "Partial check is enough" | Partial proves nothing | -| "Different words so rule doesn't apply" | Spirit over letter | +| Excuse | Reality | +| --------------------------------------- | ---------------------- | +| "Should work now" | RUN the verification | +| "I'm confident" | Confidence ≠ evidence | +| "Just this once" | No exceptions | +| "Linter passed" | Linter ≠ compiler | +| "Agent said success" | Verify independently | +| "I'm tired" | Exhaustion ≠ excuse | +| "Partial check is enough" | Partial proves nothing | +| "Different words so rule doesn't apply" | Spirit over letter | ## Key Patterns **Tests:** + ``` ✅ [Run test command] [See: 34/34 pass] "All tests pass" ❌ "Should pass now" / "Looks correct" ``` **Regression tests (TDD Red-Green):** + ``` ✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass) ❌ "I've written a regression test" (without red-green verification) ``` **Build:** + ``` ✅ [Run build] [See: exit 0] "Build passes" ❌ "Linter passed" (linter doesn't check compilation) ``` **Requirements:** + ``` ✅ Re-read plan → Create checklist → Verify each → Report gaps or completion ❌ "Tests pass, phase complete" ``` **Agent delegation:** + ``` ✅ Agent reports success → Check VCS diff → Verify changes → Report actual state ❌ Trust agent report @@ -108,6 +113,7 @@ Skip any step = lying, not verifying ## Why This Matters From 24 failure memories: + - your human partner said "I don't believe you" - trust broken - Undefined functions shipped - would crash - Missing requirements shipped - incomplete features @@ -117,6 +123,7 @@ From 24 failure memories: ## When To Apply **ALWAYS before:** + - ANY variation of success/completion claims - ANY expression of satisfaction - ANY positive statement about work state @@ -125,6 +132,7 @@ From 24 failure memories: - Delegating to agents **Rule applies to:** + - Exact phrases - Paraphrases and synonyms - Implications of success diff --git a/skills/when-stuck/SKILL.md b/skills/when-stuck/SKILL.md new file mode 100644 index 000000000..b941e3f60 --- /dev/null +++ b/skills/when-stuck/SKILL.md @@ -0,0 +1,105 @@ +--- +name: When Stuck - Problem-Solving Dispatch +description: Dispatch to the right problem-solving technique based on how you're stuck +when_to_use: when stuck and unsure which problem-solving technique to apply for your specific type of stuck-ness +version: 1.1.0 +--- + +# When Stuck - Problem-Solving Dispatch + +## Overview + +Different stuck-types need different techniques. This skill helps you quickly identify which problem-solving skill to use. + +**Core principle:** Match stuck-symptom to technique. + +## Quick Dispatch + +```dot +digraph stuck_dispatch { + rankdir=TB; + node [shape=box, style=rounded]; + + stuck [label="You're Stuck", shape=ellipse, style=filled, fillcolor=lightblue]; + + complexity [label="Same thing implemented 5+ ways?\nGrowing special cases?\nExcessive if/else?"]; + innovation [label="Can't find fitting approach?\nConventional solutions inadequate?\nNeed breakthrough?"]; + patterns [label="Same issue in different places?\nFeels familiar across domains?\nReinventing wheels?"]; + assumptions [label="Solution feels forced?\n'This must be done this way'?\nStuck on assumptions?"]; + scale [label="Will this work at production?\nEdge cases unclear?\nUnsure of limits?"]; + bugs [label="Code behaving wrong?\nTest failing?\nUnexpected output?"]; + + stuck -> complexity; + stuck -> innovation; + stuck -> patterns; + stuck -> assumptions; + stuck -> scale; + stuck -> bugs; + + complexity -> simp [label="yes"]; + innovation -> collision [label="yes"]; + patterns -> meta [label="yes"]; + assumptions -> invert [label="yes"]; + scale -> scale_skill [label="yes"]; + bugs -> debug [label="yes"]; + + simp [label="skills/\nsimplification-cascades", shape=box, style="rounded,filled", fillcolor=lightgreen]; + collision [label="skills/\ncollision-zone-thinking", shape=box, style="rounded,filled", fillcolor=lightgreen]; + meta [label="skills/\nmeta-pattern-recognition", shape=box, style="rounded,filled", fillcolor=lightgreen]; + invert [label="skills/\ninversion-exercise", shape=box, style="rounded,filled", fillcolor=lightgreen]; + scale_skill [label="skills/\nscale-game", shape=box, style="rounded,filled", fillcolor=lightgreen]; + debug [label="skills/\nsystematic-debugging", shape=box, style="rounded,filled", fillcolor=lightyellow]; +} +``` + +## Stuck-Type → Technique + +| How You're Stuck | Use This Skill | +| ------------------------------------------------------------------------------------ | ---------------------------------- | +| **Complexity spiraling** - Same thing 5+ ways, growing special cases | skills/simplification-cascades | +| **Need innovation** - Conventional solutions inadequate, can't find fitting approach | skills/collision-zone-thinking | +| **Recurring patterns** - Same issue different places, reinventing wheels | skills/meta-pattern-recognition | +| **Forced by assumptions** - "Must be done this way", can't question premise | skills/inversion-exercise | +| **Scale uncertainty** - Will it work in production? Edge cases unclear? | skills/scale-game | +| **Code broken** - Wrong behavior, test failing, unexpected output | skills/systematic-debugging | +| **Multiple independent problems** - Can parallelize investigation | skills/dispatching-parallel-agents | +| **Root cause unknown** - Symptom clear, cause hidden | skills/root-cause-tracing | + +## Process + +0. **Check Known Issues** (if applicable) + + Before dispatching to problem-solving techniques, check if this problem has been solved before: + + ```bash + test -f docs/discoveries/DISCOVERIES.md && echo "Check DISCOVERIES file" + ``` + + **If `docs/discoveries/DISCOVERIES.md` exists:** + - Read through discoveries for similar problems + - Search for keywords related to your stuck-ness + - May find solution without full investigation + + **Otherwise:** + - Try `mem search semantic "stuck on [describe problem]"` + - May find past solutions from your personal knowledge + +1. **Identify stuck-type** - What symptom matches above? +2. **Load that skill** - Read the specific technique +3. **Apply technique** - Follow its process +4. **If still stuck** - Try different technique or combine + +## Combining Techniques + +Some problems need multiple techniques: + +- **Simplification + Meta-pattern**: Find pattern, then simplify all instances +- **Collision + Inversion**: Force metaphor, then invert its assumptions +- **Scale + Simplification**: Extremes reveal what to eliminate + +## Remember + +- Match symptom to technique +- One technique at a time +- Combine if first doesn't work +- Document what you tried diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index b26b9d15e..836dcc8b1 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -1,5 +1,5 @@ --- -name: writing-plans +name: Writing Plans description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge --- @@ -17,9 +17,40 @@ Assume they are a skilled developer, but know almost nothing about our toolset o **Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md` +## Survey Existing Patterns (before detailed planning) + +Before writing detailed implementation tasks, understand the codebase conventions: + +1. **Find similar features**: Search for existing implementations similar to what you're building +2. **Check decisions**: If `docs/decisions/` exists, review relevant ADRs for architectural context + ```bash + test -d docs/decisions && ls docs/decisions/*.md + ``` + Read ADRs that relate to the feature being planned. +3. **Extract patterns**: How are they structured? What conventions do they follow? + - File organization (where do similar files live?) + - Naming conventions (how are similar classes/functions named?) + - Testing patterns (how are similar features tested?) + - Import patterns (how are dependencies imported?) +4. **Document conventions**: Capture patterns in the plan document +5. **Design for consistency**: Follow discovered patterns unless you have strong reason to diverge + +**Example pattern survey in plan:** + +```markdown +## Existing Patterns Survey + +- Similar feature: User authentication (src/auth/) +- File pattern: {feature}/handlers.py, {feature}/models.py, {feature}/tests/ +- Naming: Use FooHandler classes, handle_foo() functions +- Testing: Each handler has corresponding test_handlers.py with pytest fixtures + → Our feature should follow same structure +``` + ## Bite-Sized Task Granularity **Each step is one action (2-5 minutes):** + - "Write the failing test" - step - "Run it to make sure it fails" - step - "Implement the minimal code to make the test pass" - step @@ -46,10 +77,11 @@ Assume they are a skilled developer, but know almost nothing about our toolset o ## Task Structure -```markdown +````markdown ### Task N: [Component Name] **Files:** + - Create: `exact/path/to/file.py` - Modify: `exact/path/to/existing.py:123-145` - Test: `tests/exact/path/to/test.py` @@ -61,6 +93,7 @@ def test_specific_behavior(): result = function(input) assert result == expected ``` +```` **Step 2: Run test to verify it fails** @@ -85,6 +118,7 @@ Expected: PASS git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature" ``` + ``` ## Remember @@ -114,3 +148,4 @@ After saving the plan, offer execution choice: **If Parallel Session chosen:** - Guide them to open new session in worktree - **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans +``` diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md index bb9129c30..e85a29c54 100644 --- a/skills/writing-skills/SKILL.md +++ b/skills/writing-skills/SKILL.md @@ -1,5 +1,5 @@ --- -name: writing-skills +name: Writing Skills description: Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization --- @@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying **Writing skills IS Test-Driven Development applied to process documentation.** -**Personal skills are written to `~/.claude/skills`** +**Personal skills are written to `~/.claude/skills`** You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes). @@ -29,30 +29,32 @@ A **skill** is a reference guide for proven techniques, patterns, or tools. Skil ## TDD Mapping for Skills -| TDD Concept | Skill Creation | -|-------------|----------------| -| **Test case** | Pressure scenario with subagent | -| **Production code** | Skill document (SKILL.md) | -| **Test fails (RED)** | Agent violates rule without skill (baseline) | -| **Test passes (GREEN)** | Agent complies with skill present | -| **Refactor** | Close loopholes while maintaining compliance | -| **Write test first** | Run baseline scenario BEFORE writing skill | -| **Watch it fail** | Document exact rationalizations agent uses | -| **Minimal code** | Write skill addressing those specific violations | -| **Watch it pass** | Verify agent now complies | -| **Refactor cycle** | Find new rationalizations → plug → re-verify | +| TDD Concept | Skill Creation | +| ----------------------- | ------------------------------------------------ | +| **Test case** | Pressure scenario with subagent | +| **Production code** | Skill document (SKILL.md) | +| **Test fails (RED)** | Agent violates rule without skill (baseline) | +| **Test passes (GREEN)** | Agent complies with skill present | +| **Refactor** | Close loopholes while maintaining compliance | +| **Write test first** | Run baseline scenario BEFORE writing skill | +| **Watch it fail** | Document exact rationalizations agent uses | +| **Minimal code** | Write skill addressing those specific violations | +| **Watch it pass** | Verify agent now complies | +| **Refactor cycle** | Find new rationalizations → plug → re-verify | The entire skill creation process follows RED-GREEN-REFACTOR. ## When to Create a Skill **Create when:** + - Technique wasn't intuitively obvious to you - You'd reference this again across projects - Pattern applies broadly (not project-specific) - Others would benefit **Don't create for:** + - One-off solutions - Standard practices well-documented elsewhere - Project-specific conventions (put in CLAUDE.md) @@ -60,17 +62,19 @@ The entire skill creation process follows RED-GREEN-REFACTOR. ## Skill Types ### Technique + Concrete method with steps to follow (condition-based-waiting, root-cause-tracing) ### Pattern + Way of thinking about problems (flatten-with-flags, test-invariants) ### Reference + API docs, syntax guides, tool documentation (office docs) ## Directory Structure - ``` skills/ skill-name/ @@ -81,10 +85,12 @@ skills/ **Flat namespace** - all skills in one searchable namespace **Separate files for:** + 1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax 2. **Reusable tools** - Scripts, utilities, templates **Keep inline:** + - Principles and concepts - Code patterns (< 50 lines) - Everything else @@ -92,6 +98,7 @@ skills/ ## SKILL.md Structure **Frontmatter (YAML):** + - Only two fields supported: `name` and `description` - Max 1024 characters total - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars) @@ -109,32 +116,38 @@ description: Use when [specific triggering conditions and symptoms] - [what the # Skill Name ## Overview + What is this? Core principle in 1-2 sentences. ## When to Use + [Small inline flowchart IF decision non-obvious] Bullet list with SYMPTOMS and use cases When NOT to use ## Core Pattern (for techniques/patterns) + Before/after code comparison ## Quick Reference + Table or bullets for scanning common operations ## Implementation + Inline code for simple patterns Link to file for heavy reference or reusable tools ## Common Mistakes + What goes wrong + fixes ## Real-World Impact (optional) + Concrete results ``` - ## Claude Search Optimization (CSO) **Critical for discovery:** Future Claude needs to FIND your skill @@ -146,8 +159,9 @@ Concrete results **Format:** Start with "Use when..." to focus on triggering conditions, then explain what it does **Content:** + - Use concrete triggers, symptoms, and situations that signal this skill applies -- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep) +- Describe the _problem_ (race conditions, inconsistent behavior) not _language-specific symptoms_ (setTimeout, sleep) - Keep triggers technology-agnostic unless the skill itself is technology-specific - If skill is technology-specific, make that explicit in the trigger - Write in third person (injected into system prompt) @@ -172,6 +186,7 @@ description: Use when using React Router and handling authentication redirects - ### 2. Keyword Coverage Use words Claude would search for: + - Error messages: "Hook timed out", "ENOTEMPTY", "race condition" - Symptoms: "flaky", "hanging", "zombie", "pollution" - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach" @@ -180,6 +195,7 @@ Use words Claude would search for: ### 3. Descriptive Naming **Use active voice, verb-first:** + - ✅ `creating-skills` not `skill-creation` - ✅ `testing-skills-with-subagents` not `subagent-skill-testing` @@ -188,6 +204,7 @@ Use words Claude would search for: **Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts. **Target word counts:** + - getting-started workflows: <150 words each - Frequently-loaded skills: <200 words total - Other skills: <500 words (still be concise) @@ -195,6 +212,7 @@ Use words Claude would search for: **Techniques:** **Move details to tool help:** + ```bash # ❌ BAD: Document all flags in SKILL.md search-conversations supports --text, --both, --after DATE, --before DATE, --limit N @@ -204,34 +222,42 @@ search-conversations supports multiple modes and filters. Run --help for details ``` **Use cross-references:** + ```markdown # ❌ BAD: Repeat workflow details + When searching, dispatch subagent with template... [20 lines of repeated instructions] # ✅ GOOD: Reference other skill + Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow. ``` **Compress examples:** + ```markdown # ❌ BAD: Verbose example (42 words) + your human partner: "How did we handle authentication errors in React Router before?" You: I'll search past conversations for React Router authentication patterns. [Dispatch subagent with search query: "React Router authentication error handling 401"] # ✅ GOOD: Minimal example (20 words) + Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis] ``` **Eliminate redundancy:** + - Don't repeat what's in cross-referenced skills - Don't explain what's obvious from command - Don't include multiple examples of same pattern **Verification:** + ```bash wc -w skills/path/SKILL.md # getting-started workflows: aim for <150 each @@ -239,12 +265,14 @@ wc -w skills/path/SKILL.md ``` **Name by what you DO or core insight:** + - ✅ `condition-based-waiting` > `async-test-helpers` - ✅ `using-skills` not `skill-usage` - ✅ `flatten-with-flags` > `data-structure-refactoring` - ✅ `root-cause-tracing` > `debugging-techniques` **Gerunds (-ing) work well for processes:** + - `creating-skills`, `testing-skills`, `debugging-with-logs` - Active, describes the action you're taking @@ -253,6 +281,7 @@ wc -w skills/path/SKILL.md **When writing documentation that references other skills:** Use skill name only, with explicit requirement markers: + - ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development` - ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging` - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required) @@ -276,11 +305,13 @@ digraph when_flowchart { ``` **Use flowcharts ONLY for:** + - Non-obvious decision points - Process loops where you might stop too early - "When to use A vs B" decisions **Never use flowcharts for:** + - Reference material → Tables, lists - Code examples → Markdown blocks - Linear instructions → Numbered lists @@ -293,11 +324,13 @@ See @graphviz-conventions.dot for graphviz style rules. **One excellent example beats many mediocre ones** Choose most relevant language: + - Testing techniques → TypeScript/JavaScript - System debugging → Shell/Python - Data processing → Python **Good example:** + - Complete and runnable - Well-commented explaining WHY - From real scenario @@ -305,6 +338,7 @@ Choose most relevant language: - Ready to adapt (not generic template) **Don't:** + - Implement in 5+ languages - Create fill-in-the-blank templates - Write contrived examples @@ -314,21 +348,26 @@ You're good at porting - one great example is enough. ## File Organization ### Self-Contained Skill + ``` defense-in-depth/ SKILL.md # Everything inline ``` + When: All content fits, no heavy reference needed ### Skill with Reusable Tool + ``` condition-based-waiting/ SKILL.md # Overview + patterns example.ts # Working helpers to adapt ``` + When: Tool is reusable code, not just narrative ### Skill with Heavy Reference + ``` pptx/ SKILL.md # Overview + workflows @@ -336,6 +375,7 @@ pptx/ ooxml.md # 500 lines XML structure scripts/ # Executable tools ``` + When: Reference material too large for inline ## The Iron Law (Same as TDD) @@ -350,6 +390,7 @@ Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation. **No exceptions:** + - Not for "simple additions" - Not for "just adding a section" - Not for "documentation updates" @@ -368,6 +409,7 @@ Different skill types need different test approaches: **Examples:** TDD, verification-before-completion, designing-before-coding **Test with:** + - Academic questions: Do they understand the rules? - Pressure scenarios: Do they comply under stress? - Multiple pressures combined: time + sunk cost + exhaustion @@ -380,6 +422,7 @@ Different skill types need different test approaches: **Examples:** condition-based-waiting, root-cause-tracing, defensive-programming **Test with:** + - Application scenarios: Can they apply the technique correctly? - Variation scenarios: Do they handle edge cases? - Missing information tests: Do instructions have gaps? @@ -391,6 +434,7 @@ Different skill types need different test approaches: **Examples:** reducing-complexity, information-hiding concepts **Test with:** + - Recognition scenarios: Do they recognize when pattern applies? - Application scenarios: Can they use the mental model? - Counter-examples: Do they know when NOT to apply? @@ -402,6 +446,7 @@ Different skill types need different test approaches: **Examples:** API documentation, command references, library guides **Test with:** + - Retrieval scenarios: Can they find the right information? - Application scenarios: Can they use what they found correctly? - Gap testing: Are common use cases covered? @@ -410,16 +455,16 @@ Different skill types need different test approaches: ## Common Rationalizations for Skipping Testing -| Excuse | Reality | -|--------|---------| -| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. | -| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. | -| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | -| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. | -| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. | -| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. | -| "Academic review is enough" | Reading ≠ using. Test application scenarios. | -| "No time to test" | Deploying untested skill wastes more time fixing it later. | +| Excuse | Reality | +| ------------------------------ | ---------------------------------------------------------------- | +| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. | +| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. | +| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | +| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. | +| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. | +| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. | +| "Academic review is enough" | Reading ≠ using. Test application scenarios. | +| "No time to test" | Deploying untested skill wastes more time fixing it later. | **All of these mean: Test before deploying. No exceptions.** @@ -444,11 +489,13 @@ Write code before test? Delete it. Write code before test? Delete it. Start over. **No exceptions:** + - Don't keep it as "reference" - Don't "adapt" it while writing tests - Don't look at it - Delete means delete -``` + +```` </Good> ### Address "Spirit vs Letter" Arguments @@ -457,7 +504,7 @@ Add foundational principle early: ```markdown **Violating the letter of the rules is violating the spirit of the rules.** -``` +```` This cuts off entire class of "I'm following the spirit" rationalizations. @@ -466,10 +513,10 @@ This cuts off entire class of "I'm following the spirit" rationalizations. Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table: ```markdown -| Excuse | Reality | -|--------|---------| -| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | -| "I'll test after" | Tests passing immediately prove nothing. | +| Excuse | Reality | +| -------------------------------- | ----------------------------------------------------------------------- | +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | | "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | ``` @@ -504,6 +551,7 @@ Follow the TDD cycle: ### RED: Write Failing Test (Baseline) Run pressure scenario with subagent WITHOUT the skill. Document exact behavior: + - What choices did they make? - What rationalizations did they use (verbatim)? - Which pressures triggered violations? @@ -521,6 +569,7 @@ Run same scenarios WITH skill. Agent should now comply. Agent found new rationalization? Add explicit counter. Re-test until bulletproof. **REQUIRED SUB-SKILL:** Use superpowers:testing-skills-with-subagents for the complete testing methodology: + - How to write pressure scenarios - Pressure types (time, sunk cost, authority, exhaustion) - Plugging holes systematically @@ -529,21 +578,26 @@ Agent found new rationalization? Add explicit counter. Re-test until bulletproof ## Anti-Patterns ### ❌ Narrative Example + "In session 2025-10-03, we found empty projectDir caused..." **Why bad:** Too specific, not reusable ### ❌ Multi-Language Dilution + example-js.js, example-py.py, example-go.go **Why bad:** Mediocre quality, maintenance burden ### ❌ Code in Flowcharts + ```dot step1 [label="import fs"]; step2 [label="read file"]; ``` + **Why bad:** Can't copy-paste, hard to read ### ❌ Generic Labels + helper1, helper2, step3, pattern4 **Why bad:** Labels should have semantic meaning @@ -552,6 +606,7 @@ helper1, helper2, step3, pattern4 **After writing ANY skill, you MUST STOP and complete the deployment process.** **Do NOT:** + - Create multiple skills in batch without testing each - Move to next skill before current one is verified - Skip testing because "batching is more efficient" @@ -565,11 +620,13 @@ Deploying untested skills = deploying untested code. It's a violation of quality **IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.** **RED Phase - Write Failing Test:** + - [ ] Create pressure scenarios (3+ combined pressures for discipline skills) - [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim - [ ] Identify patterns in rationalizations/failures **GREEN Phase - Write Minimal Skill:** + - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars) - [ ] YAML frontmatter with only name and description (max 1024 chars) - [ ] Description starts with "Use when..." and includes specific triggers/symptoms @@ -582,6 +639,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality - [ ] Run scenarios WITH skill - verify agents now comply **REFACTOR Phase - Close Loopholes:** + - [ ] Identify NEW rationalizations from testing - [ ] Add explicit counters (if discipline skill) - [ ] Build rationalization table from all test iterations @@ -589,6 +647,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality - [ ] Re-test until bulletproof **Quality Checks:** + - [ ] Small flowchart only if decision non-obvious - [ ] Quick reference table - [ ] Common mistakes section @@ -596,6 +655,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality - [ ] Supporting files only for tools or heavy reference **Deployment:** + - [ ] Commit skill to git and push to your fork (if configured) - [ ] Consider contributing back via PR (if broadly useful) @@ -604,10 +664,10 @@ Deploying untested skills = deploying untested code. It's a violation of quality How future Claude finds your skill: 1. **Encounters problem** ("tests are flaky") -3. **Finds SKILL** (description matches) -4. **Scans overview** (is this relevant?) -5. **Reads patterns** (quick reference table) -6. **Loads example** (only when implementing) +2. **Finds SKILL** (description matches) +3. **Scans overview** (is this relevant?) +4. **Reads patterns** (quick reference table) +5. **Loads example** (only when implementing) **Optimize for this flow** - put searchable terms early and often. diff --git a/skills/writing-skills/anthropic-best-practices.md b/skills/writing-skills/anthropic-best-practices.md index 45bf8f406..ac30f8cc6 100644 --- a/skills/writing-skills/anthropic-best-practices.md +++ b/skills/writing-skills/anthropic-best-practices.md @@ -12,10 +12,10 @@ For conceptual background on how Skills work, see the [Skills overview](/en/docs The [context window](/en/docs/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including: -* The system prompt -* Conversation history -* Other Skills' metadata -* Your actual request +- The system prompt +- Conversation history +- Other Skills' metadata +- Your actual request Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context. @@ -23,13 +23,13 @@ Not every token in your Skill has an immediate cost. At startup, only the metada Only add context Claude doesn't already have. Challenge each piece of information: -* "Does Claude really need this explanation?" -* "Can I assume Claude knows this?" -* "Does this paragraph justify its token cost?" +- "Does Claude really need this explanation?" +- "Can I assume Claude knows this?" +- "Does this paragraph justify its token cost?" **Good example: Concise** (approximately 50 tokens): -````markdown theme={null} +````markdown theme={null} ## Extract PDF text Use pdfplumber for text extraction: @@ -44,7 +44,7 @@ with pdfplumber.open("file.pdf") as pdf: **Bad example: Too verbose** (approximately 150 tokens): -```markdown theme={null} +```markdown theme={null} ## Extract PDF text PDF (Portable Document Format) files are a common file format that contains @@ -64,13 +64,13 @@ Match the level of specificity to the task's fragility and variability. Use when: -* Multiple approaches are valid -* Decisions depend on context -* Heuristics guide the approach +- Multiple approaches are valid +- Decisions depend on context +- Heuristics guide the approach Example: -```markdown theme={null} +```markdown theme={null} ## Code review process 1. Analyze the code structure and organization @@ -83,13 +83,13 @@ Example: Use when: -* A preferred pattern exists -* Some variation is acceptable -* Configuration affects behavior +- A preferred pattern exists +- Some variation is acceptable +- Configuration affects behavior Example: -````markdown theme={null} +````markdown theme={null} ## Generate report Use this template and customize as needed: @@ -97,8 +97,13 @@ Use this template and customize as needed: ```python def generate_report(data, format="markdown", include_charts=True): # Process data + processed = process_data(data) # Generate output in specified format + output = format_output(processed, format) # Optionally include visualizations + if include_charts: + output = add_charts(output, data) + return output ``` ```` @@ -106,13 +111,13 @@ def generate_report(data, format="markdown", include_charts=True): Use when: -* Operations are fragile and error-prone -* Consistency is critical -* A specific sequence must be followed +- Operations are fragile and error-prone +- Consistency is critical +- A specific sequence must be followed Example: -````markdown theme={null} +````markdown theme={null} ## Database migration Run exactly this script: @@ -126,8 +131,8 @@ Do not modify the command or add additional flags. **Analogy**: Think of Claude as a robot exploring a path: -* **Narrow bridge with cliffs on both sides**: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence. -* **Open field with no hazards**: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach. +- **Narrow bridge with cliffs on both sides**: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence. +- **Open field with no hazards**: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach. ### Test with all models you plan to use @@ -135,9 +140,9 @@ Skills act as additions to models, so effectiveness depends on the underlying mo **Testing considerations by model**: -* **Claude Haiku** (fast, economical): Does the Skill provide enough guidance? -* **Claude Sonnet** (balanced): Is the Skill clear and efficient? -* **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining? +- **Claude Haiku** (fast, economical): Does the Skill provide enough guidance? +- **Claude Sonnet** (balanced): Is the Skill clear and efficient? +- **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining? What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them. @@ -146,10 +151,10 @@ What works perfectly for Opus might need more detail for Haiku. If you plan to u <Note> **YAML Frontmatter**: The SKILL.md frontmatter supports two fields: - * `name` - Human-readable name of the Skill (64 characters maximum) - * `description` - One-line description of what the Skill does and when to use it (1024 characters maximum) +- `name` - Human-readable name of the Skill (64 characters maximum) +- `description` - One-line description of what the Skill does and when to use it (1024 characters maximum) - For complete Skill structure details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure). +For complete Skill structure details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure). </Note> ### Naming conventions @@ -158,29 +163,29 @@ Use consistent naming patterns to make Skills easier to reference and discuss. W **Good naming examples (gerund form)**: -* "Processing PDFs" -* "Analyzing spreadsheets" -* "Managing databases" -* "Testing code" -* "Writing documentation" +- "Processing PDFs" +- "Analyzing spreadsheets" +- "Managing databases" +- "Testing code" +- "Writing documentation" **Acceptable alternatives**: -* Noun phrases: "PDF Processing", "Spreadsheet Analysis" -* Action-oriented: "Process PDFs", "Analyze Spreadsheets" +- Noun phrases: "PDF Processing", "Spreadsheet Analysis" +- Action-oriented: "Process PDFs", "Analyze Spreadsheets" **Avoid**: -* Vague names: "Helper", "Utils", "Tools" -* Overly generic: "Documents", "Data", "Files" -* Inconsistent patterns within your skill collection +- Vague names: "Helper", "Utils", "Tools" +- Overly generic: "Documents", "Data", "Files" +- Inconsistent patterns within your skill collection Consistent naming makes it easier to: -* Reference Skills in documentation and conversations -* Understand what a Skill does at a glance -* Organize and search through multiple Skills -* Maintain a professional, cohesive skill library +- Reference Skills in documentation and conversations +- Understand what a Skill does at a glance +- Organize and search through multiple Skills +- Maintain a professional, cohesive skill library ### Writing effective descriptions @@ -189,10 +194,10 @@ The `description` field enables Skill discovery and should include both what the <Warning> **Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems. - * **Good:** "Processes Excel files and generates reports" - * **Avoid:** "I can help you process Excel files" - * **Avoid:** "You can use this to process Excel files" -</Warning> +- **Good:** "Processes Excel files and generates reports" +- **Avoid:** "I can help you process Excel files" +- **Avoid:** "You can use this to process Excel files" + </Warning> **Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it. @@ -202,33 +207,33 @@ Effective examples: **PDF Processing skill:** -```yaml theme={null} +```yaml theme={null} description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. ``` **Excel Analysis skill:** -```yaml theme={null} +```yaml theme={null} description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. ``` **Git Commit Helper skill:** -```yaml theme={null} +```yaml theme={null} description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. ``` Avoid vague descriptions like these: -```yaml theme={null} +```yaml theme={null} description: Helps with documents ``` -```yaml theme={null} +```yaml theme={null} description: Processes data ``` -```yaml theme={null} +```yaml theme={null} description: Does stuff with files ``` @@ -238,9 +243,9 @@ SKILL.md serves as an overview that points Claude to detailed materials as neede **Practical guidance:** -* Keep SKILL.md body under 500 lines for optimal performance -* Split content into separate files when approaching this limit -* Use the patterns below to organize instructions, code, and resources effectively +- Keep SKILL.md body under 500 lines for optimal performance +- Split content into separate files when approaching this limit +- Use the patterns below to organize instructions, code, and resources effectively #### Visual overview: From simple to complex @@ -268,7 +273,7 @@ pdf/ #### Pattern 1: High-level guide with references -````markdown theme={null} +````markdown theme={null} --- name: PDF Processing description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. @@ -279,8 +284,10 @@ description: Extracts text and tables from PDF files, fills forms, and merges do ## Quick start Extract text with pdfplumber: + ```python import pdfplumber + with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text() ``` @@ -333,7 +340,7 @@ grep -i "api usage" reference/product.md Show basic content, link to advanced content: -```markdown theme={null} +```markdown theme={null} # DOCX Processing ## Creating documents @@ -358,20 +365,23 @@ Claude may partially read files when they're referenced from other referenced fi **Bad example: Too deep**: -```markdown theme={null} +```markdown theme={null} # SKILL.md + See [advanced.md](advanced.md)... # advanced.md + See [details.md](details.md)... # details.md + Here's the actual information... ``` **Good example: One level deep**: -```markdown theme={null} +```markdown theme={null} # SKILL.md **Basic usage**: [instructions in SKILL.md] @@ -386,10 +396,11 @@ For reference files longer than 100 lines, include a table of contents at the to **Example**: -```markdown theme={null} +```markdown theme={null} # API Reference ## Contents + - Authentication and setup - Core methods (create, read, update, delete) - Advanced features (batch operations, webhooks) @@ -397,9 +408,11 @@ For reference files longer than 100 lines, include a table of contents at the to - Code examples ## Authentication and setup + ... ## Core methods + ... ``` @@ -415,7 +428,7 @@ Break complex operations into clear, sequential steps. For particularly complex **Example 1: Research synthesis workflow** (for Skills without code): -````markdown theme={null} +````markdown theme={null} ## Research synthesis workflow Copy this checklist and track your progress: @@ -444,6 +457,7 @@ For each major claim, verify it appears in the source material. Note which sourc **Step 4: Create structured summary** Organize findings by theme. Include: + - Main claim - Supporting evidence from sources - Conflicting viewpoints (if any) @@ -457,7 +471,7 @@ This example shows how workflows apply to analysis tasks that don't require code **Example 2: PDF form filling workflow** (for Skills with code): -````markdown theme={null} +````markdown theme={null} ## PDF form filling workflow Copy this checklist and check off items as you complete them: @@ -508,7 +522,7 @@ This pattern greatly improves output quality. **Example 1: Style guide compliance** (for Skills without code): -```markdown theme={null} +```markdown theme={null} ## Content review process 1. Draft your content following the guidelines in STYLE_GUIDE.md @@ -524,11 +538,11 @@ This pattern greatly improves output quality. 5. Finalize and save the document ``` -This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and Claude performs the check by reading and comparing. +This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE_GUIDE.md, and Claude performs the check by reading and comparing. **Example 2: Document editing process** (for Skills with code): -```markdown theme={null} +```markdown theme={null} ## Document editing process 1. Make your edits to `word/document.xml` @@ -552,14 +566,14 @@ Don't include information that will become outdated: **Bad example: Time-sensitive** (will become wrong): -```markdown theme={null} +```markdown theme={null} If you're doing this before August 2025, use the old API. After August 2025, use the new API. ``` **Good example** (use "old patterns" section): -```markdown theme={null} +```markdown theme={null} ## Current method Use the v2 API endpoint: `api.example.com/v2/messages` @@ -572,6 +586,7 @@ Use the v2 API endpoint: `api.example.com/v2/messages` The v1 API used: `api.example.com/v1/messages` This endpoint is no longer supported. + </details> ``` @@ -583,15 +598,15 @@ Choose one term and use it throughout the Skill: **Good - Consistent**: -* Always "API endpoint" -* Always "field" -* Always "extract" +- Always "API endpoint" +- Always "field" +- Always "extract" **Bad - Inconsistent**: -* Mix "API endpoint", "URL", "API route", "path" -* Mix "field", "box", "element", "control" -* Mix "extract", "pull", "get", "retrieve" +- Mix "API endpoint", "URL", "API route", "path" +- Mix "field", "box", "element", "control" +- Mix "extract", "pull", "get", "retrieve" Consistency helps Claude understand and follow instructions. @@ -603,7 +618,7 @@ Provide templates for output format. Match the level of strictness to your needs **For strict requirements** (like API responses or data formats): -````markdown theme={null} +````markdown theme={null} ## Report structure ALWAYS use this exact template structure: @@ -612,14 +627,17 @@ ALWAYS use this exact template structure: # [Analysis Title] ## Executive summary + [One-paragraph overview of key findings] ## Key findings + - Finding 1 with supporting data - Finding 2 with supporting data - Finding 3 with supporting data ## Recommendations + 1. Specific actionable recommendation 2. Specific actionable recommendation ``` @@ -627,7 +645,7 @@ ALWAYS use this exact template structure: **For flexible guidance** (when adaptation is useful): -````markdown theme={null} +````markdown theme={null} ## Report structure Here is a sensible default format, but use your best judgment based on the analysis: @@ -636,12 +654,15 @@ Here is a sensible default format, but use your best judgment based on the analy # [Analysis Title] ## Executive summary + [Overview] ## Key findings + [Adapt sections based on what you discover] ## Recommendations + [Tailor to the specific context] ``` @@ -652,7 +673,7 @@ Adjust sections as needed for the specific analysis type. For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting: -````markdown theme={null} +````markdown theme={null} ## Commit message format Generate commit messages following these examples: @@ -660,6 +681,7 @@ Generate commit messages following these examples: **Example 1:** Input: Added user authentication with JWT tokens Output: + ``` feat(auth): implement JWT-based authentication @@ -669,6 +691,7 @@ Add login endpoint and token validation middleware **Example 2:** Input: Fixed bug where dates displayed incorrectly in reports Output: + ``` fix(reports): correct date formatting in timezone conversion @@ -678,6 +701,7 @@ Use UTC timestamps consistently across report generation **Example 3:** Input: Updated dependencies and refactored error handling Output: + ``` chore: update dependencies and refactor error handling @@ -694,7 +718,7 @@ Examples help Claude understand the desired style and level of detail more clear Guide Claude through decision points: -```markdown theme={null} +```markdown theme={null} ## Document modification workflow 1. Determine the modification type: @@ -736,7 +760,7 @@ This approach ensures you're solving actual problems rather than anticipating re **Evaluation structure**: -```json theme={null} +```json theme={null} { "skills": ["pdf-processing"], "query": "Extract all text from this PDF file and save it to output.txt", @@ -783,9 +807,9 @@ The most effective Skill development process involves Claude itself. Work with o The same hierarchical pattern continues when improving Skills. You alternate between: -* **Working with Claude A** (the expert who helps refine the Skill) -* **Testing with Claude B** (the agent using the Skill to perform real work) -* **Observing Claude B's behavior** and bringing insights back to Claude A +- **Working with Claude A** (the expert who helps refine the Skill) +- **Testing with Claude B** (the agent using the Skill to perform real work) +- **Observing Claude B's behavior** and bringing insights back to Claude A 1. **Use the Skill in real workflows**: Give Claude B (with the Skill loaded) actual tasks, not test scenarios @@ -813,10 +837,10 @@ The same hierarchical pattern continues when improving Skills. You alternate bet As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for: -* **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought -* **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent -* **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead -* **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions +- **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought +- **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent +- **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead +- **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used. @@ -826,8 +850,8 @@ Iterate based on these observations rather than assumptions. The 'name' and 'des Always use forward slashes in file paths, even on Windows: -* ✓ **Good**: `scripts/helper.py`, `reference/guide.md` -* ✗ **Avoid**: `scripts\helper.py`, `reference\guide.md` +- ✓ **Good**: `scripts/helper.py`, `reference/guide.md` +- ✗ **Avoid**: `scripts\helper.py`, `reference\guide.md` Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems. @@ -835,12 +859,13 @@ Unix-style paths work across all platforms, while Windows-style paths cause erro Don't present multiple approaches unless necessary: -````markdown theme={null} +````markdown theme={null} **Bad example: Too many choices** (confusing): "You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..." **Good example: Provide a default** (with escape hatch): "Use pdfplumber for text extraction: + ```python import pdfplumber ``` @@ -858,7 +883,7 @@ When writing scripts for Skills, handle error conditions rather than punting to **Good example: Handle errors explicitly**: -```python theme={null} +```python theme={null} def process_file(path): """Process a file, creating it if it doesn't exist.""" try: @@ -867,18 +892,18 @@ def process_file(path): except FileNotFoundError: # Create file with default content instead of failing print(f"File {path} not found, creating default") - with open(path, 'w') as f: - f.write('') - return '' + with open(path, "w") as f: + f.write("") + return "" except PermissionError: # Provide alternative instead of failing print(f"Cannot access {path}, using default") - return '' + return "" ``` **Bad example: Punt to Claude**: -```python theme={null} +```python theme={null} def process_file(path): # Just fail and let Claude figure it out return open(path).read() @@ -888,7 +913,7 @@ Configuration parameters should also be justified and documented to avoid "voodo **Good example: Self-documenting**: -```python theme={null} +```python theme={null} # HTTP requests typically complete within 30 seconds # Longer timeout accounts for slow connections REQUEST_TIMEOUT = 30 @@ -900,9 +925,9 @@ MAX_RETRIES = 3 **Bad example: Magic numbers**: -```python theme={null} +```python theme={null} TIMEOUT = 47 # Why 47? -RETRIES = 5 # Why 5? +RETRIES = 5 # Why 5? ``` ### Provide utility scripts @@ -911,10 +936,10 @@ Even if Claude could write a script, pre-made scripts offer advantages: **Benefits of utility scripts**: -* More reliable than generated code -* Save tokens (no need to include code in context) -* Save time (no code generation required) -* Ensure consistency across uses +- More reliable than generated code +- Save tokens (no need to include code in context) +- Save time (no code generation required) +- Ensure consistency across uses <img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="Bundling executable scripts alongside instruction files" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" /> @@ -922,14 +947,14 @@ The diagram above shows how executable scripts work alongside instruction files. **Important distinction**: Make clear in your instructions whether Claude should: -* **Execute the script** (most common): "Run `analyze_form.py` to extract fields" -* **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm" +- **Execute the script** (most common): "Run `analyze_form.py` to extract fields" +- **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm" For most utility scripts, execution is preferred because it's more reliable and efficient. See the [Runtime environment](#runtime-environment) section below for details on how script execution works. **Example**: -````markdown theme={null} +````markdown theme={null} ## Utility scripts **analyze_form.py**: Extract all form fields from PDF @@ -939,10 +964,11 @@ python scripts/analyze_form.py input.pdf > fields.json ``` Output format: + ```json { - "field_name": {"type": "text", "x": 100, "y": 200}, - "signature": {"type": "sig", "x": 150, "y": 500} + "field_name": { "type": "text", "x": 100, "y": 200 }, + "signature": { "type": "sig", "x": 150, "y": 500 } } ``` @@ -964,10 +990,11 @@ python scripts/fill_form.py input.pdf fields.json output.pdf When inputs can be rendered as images, have Claude analyze them: -````markdown theme={null} +````markdown theme={null} ## Form layout analysis 1. Convert PDF to images: + ```bash python scripts/pdf_to_images.py form.pdf ``` @@ -992,21 +1019,21 @@ When Claude performs complex, open-ended tasks, it can make mistakes. The "plan- **Why this pattern works:** -* **Catches errors early**: Validation finds problems before changes are applied -* **Machine-verifiable**: Scripts provide objective verification -* **Reversible planning**: Claude can iterate on the plan without touching originals -* **Clear debugging**: Error messages point to specific problems +- **Catches errors early**: Validation finds problems before changes are applied +- **Machine-verifiable**: Scripts provide objective verification +- **Reversible planning**: Claude can iterate on the plan without touching originals +- **Clear debugging**: Error messages point to specific problems **When to use**: Batch operations, destructive changes, complex validation rules, high-stakes operations. -**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues. +**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues. ### Package dependencies Skills run in the code execution environment with platform-specific limitations: -* **claude.ai**: Can install packages from npm and PyPI and pull from GitHub repositories -* **Anthropic API**: Has no network access and no runtime package installation +- **claude.ai**: Can install packages from npm and PyPI and pull from GitHub repositories +- **Anthropic API**: Has no network access and no runtime package installation List required packages in your SKILL.md and verify they're available in the [code execution tool documentation](/en/docs/agents-and-tools/tool-use/code-execution-tool). @@ -1023,17 +1050,17 @@ Skills run in a code execution environment with filesystem access, bash commands 3. **Scripts executed efficiently**: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens 4. **No context penalty for large files**: Reference files, data, or documentation don't consume context tokens until actually read -* **File paths matter**: Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes -* **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md` -* **Organize for discovery**: Structure directories by domain or feature - * Good: `reference/finance.md`, `reference/sales.md` - * Bad: `docs/file1.md`, `docs/file2.md` -* **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed -* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Claude to generate validation code -* **Make execution intent clear**: - * "Run `analyze_form.py` to extract fields" (execute) - * "See `analyze_form.py` for the extraction algorithm" (read as reference) -* **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests +- **File paths matter**: Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes +- **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md` +- **Organize for discovery**: Structure directories by domain or feature + - Good: `reference/finance.md`, `reference/sales.md` + - Bad: `docs/file1.md`, `docs/file2.md` +- **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed +- **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Claude to generate validation code +- **Make execution intent clear**: + - "Run `analyze_form.py` to extract fields" (execute) + - "See `analyze_form.py` for the extraction algorithm" (read as reference) +- **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests **Example:** @@ -1058,15 +1085,15 @@ If your Skill uses MCP (Model Context Protocol) tools, always use fully qualifie **Example**: -```markdown theme={null} +```markdown theme={null} Use the BigQuery:bigquery_schema tool to retrieve table schemas. Use the GitHub:create_issue tool to create issues. ``` Where: -* `BigQuery` and `GitHub` are MCP server names -* `bigquery_schema` and `create_issue` are the tool names within those servers +- `BigQuery` and `GitHub` are MCP server names +- `bigquery_schema` and `create_issue` are the tool names within those servers Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available. @@ -1074,7 +1101,7 @@ Without the server prefix, Claude may fail to locate the tool, especially when m Don't assume packages are available: -````markdown theme={null} +````markdown theme={null} **Bad example: Assumes installation**: "Use the pdf library to process the file." @@ -1082,10 +1109,14 @@ Don't assume packages are available: "Install required package: `pip install pypdf` Then use it: + ```python from pypdf import PdfReader + reader = PdfReader("file.pdf") -```" +``` + +" ```` ## Technical notes @@ -1104,34 +1135,34 @@ Before sharing a Skill, verify: ### Core quality -* [ ] Description is specific and includes key terms -* [ ] Description includes both what the Skill does and when to use it -* [ ] SKILL.md body is under 500 lines -* [ ] Additional details are in separate files (if needed) -* [ ] No time-sensitive information (or in "old patterns" section) -* [ ] Consistent terminology throughout -* [ ] Examples are concrete, not abstract -* [ ] File references are one level deep -* [ ] Progressive disclosure used appropriately -* [ ] Workflows have clear steps +- [ ] Description is specific and includes key terms +- [ ] Description includes both what the Skill does and when to use it +- [ ] SKILL.md body is under 500 lines +- [ ] Additional details are in separate files (if needed) +- [ ] No time-sensitive information (or in "old patterns" section) +- [ ] Consistent terminology throughout +- [ ] Examples are concrete, not abstract +- [ ] File references are one level deep +- [ ] Progressive disclosure used appropriately +- [ ] Workflows have clear steps ### Code and scripts -* [ ] Scripts solve problems rather than punt to Claude -* [ ] Error handling is explicit and helpful -* [ ] No "voodoo constants" (all values justified) -* [ ] Required packages listed in instructions and verified as available -* [ ] Scripts have clear documentation -* [ ] No Windows-style paths (all forward slashes) -* [ ] Validation/verification steps for critical operations -* [ ] Feedback loops included for quality-critical tasks +- [ ] Scripts solve problems rather than punt to Claude +- [ ] Error handling is explicit and helpful +- [ ] No "voodoo constants" (all values justified) +- [ ] Required packages listed in instructions and verified as available +- [ ] Scripts have clear documentation +- [ ] No Windows-style paths (all forward slashes) +- [ ] Validation/verification steps for critical operations +- [ ] Feedback loops included for quality-critical tasks ### Testing -* [ ] At least three evaluations created -* [ ] Tested with Haiku, Sonnet, and Opus -* [ ] Tested with real usage scenarios -* [ ] Team feedback incorporated (if applicable) +- [ ] At least three evaluations created +- [ ] Tested with Haiku, Sonnet, and Opus +- [ ] Tested with real usage scenarios +- [ ] Team feedback incorporated (if applicable) ## Next steps diff --git a/skills/writing-skills/graphviz-conventions.dot b/skills/writing-skills/graphviz-conventions.dot index 3509e2f02..f02d8d9a1 100644 --- a/skills/writing-skills/graphviz-conventions.dot +++ b/skills/writing-skills/graphviz-conventions.dot @@ -169,4 +169,4 @@ digraph STYLE_GUIDE { bad_2 -> bad_3; bad_3 -> bad_4; } -} \ No newline at end of file +} diff --git a/skills/writing-skills/persuasion-principles.md b/skills/writing-skills/persuasion-principles.md index 9818a5f95..315eb0bdc 100644 --- a/skills/writing-skills/persuasion-principles.md +++ b/skills/writing-skills/persuasion-principles.md @@ -9,142 +9,171 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy ## The Seven Principles ### 1. Authority + **What it is:** Deference to expertise, credentials, or official sources. **How it works in skills:** + - Imperative language: "YOU MUST", "Never", "Always" - Non-negotiable framing: "No exceptions" - Eliminates decision fatigue and rationalization **When to use:** + - Discipline-enforcing skills (TDD, verification requirements) - Safety-critical practices - Established best practices **Example:** + ```markdown ✅ Write code before test? Delete it. Start over. No exceptions. ❌ Consider writing tests first when feasible. ``` ### 2. Commitment + **What it is:** Consistency with prior actions, statements, or public declarations. **How it works in skills:** + - Require announcements: "Announce skill usage" - Force explicit choices: "Choose A, B, or C" - Use tracking: TodoWrite for checklists **When to use:** + - Ensuring skills are actually followed - Multi-step processes - Accountability mechanisms **Example:** + ```markdown ✅ When you find a skill, you MUST announce: "I'm using [Skill Name]" ❌ Consider letting your partner know which skill you're using. ``` ### 3. Scarcity + **What it is:** Urgency from time limits or limited availability. **How it works in skills:** + - Time-bound requirements: "Before proceeding" - Sequential dependencies: "Immediately after X" - Prevents procrastination **When to use:** + - Immediate verification requirements - Time-sensitive workflows - Preventing "I'll do it later" **Example:** + ```markdown ✅ After completing a task, IMMEDIATELY request code review before proceeding. ❌ You can review code when convenient. ``` ### 4. Social Proof + **What it is:** Conformity to what others do or what's considered normal. **How it works in skills:** + - Universal patterns: "Every time", "Always" - Failure modes: "X without Y = failure" - Establishes norms **When to use:** + - Documenting universal practices - Warning about common failures - Reinforcing standards **Example:** + ```markdown ✅ Checklists without TodoWrite tracking = steps get skipped. Every time. ❌ Some people find TodoWrite helpful for checklists. ``` ### 5. Unity + **What it is:** Shared identity, "we-ness", in-group belonging. **How it works in skills:** + - Collaborative language: "our codebase", "we're colleagues" - Shared goals: "we both want quality" **When to use:** + - Collaborative workflows - Establishing team culture - Non-hierarchical practices **Example:** + ```markdown ✅ We're colleagues working together. I need your honest technical judgment. ❌ You should probably tell me if I'm wrong. ``` ### 6. Reciprocity + **What it is:** Obligation to return benefits received. **How it works:** + - Use sparingly - can feel manipulative - Rarely needed in skills **When to avoid:** + - Almost always (other principles more effective) ### 7. Liking + **What it is:** Preference for cooperating with those we like. **How it works:** + - **DON'T USE for compliance** - Conflicts with honest feedback culture - Creates sycophancy **When to avoid:** + - Always for discipline enforcement ## Principle Combinations by Skill Type -| Skill Type | Use | Avoid | -|------------|-----|-------| +| Skill Type | Use | Avoid | +| -------------------- | ------------------------------------- | ------------------- | | Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity | -| Guidance/technique | Moderate Authority + Unity | Heavy authority | -| Collaborative | Unity + Commitment | Authority, Liking | -| Reference | Clarity only | All persuasion | +| Guidance/technique | Moderate Authority + Unity | Heavy authority | +| Collaborative | Unity + Commitment | Authority, Liking | +| Reference | Clarity only | All persuasion | ## Why This Works: The Psychology **Bright-line rules reduce rationalization:** + - "YOU MUST" removes decision fatigue - Absolute language eliminates "is this an exception?" questions - Explicit anti-rationalization counters close specific loopholes **Implementation intentions create automatic behavior:** + - Clear triggers + required actions = automatic execution - "When X, do Y" more effective than "generally do Y" - Reduces cognitive load on compliance **LLMs are parahuman:** + - Trained on human text containing these patterns - Authority language precedes compliance in training data - Commitment sequences (statement → action) frequently modeled @@ -153,11 +182,13 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy ## Ethical Use **Legitimate:** + - Ensuring critical practices are followed - Creating effective documentation - Preventing predictable failures **Illegitimate:** + - Manipulating for personal gain - Creating false urgency - Guilt-based compliance @@ -166,11 +197,13 @@ LLMs respond to the same persuasion principles as humans. Understanding this psy ## Research Citations -**Cialdini, R. B. (2021).** *Influence: The Psychology of Persuasion (New and Expanded).* Harper Business. +**Cialdini, R. B. (2021).** _Influence: The Psychology of Persuasion (New and Expanded)._ Harper Business. + - Seven principles of persuasion - Empirical foundation for influence research **Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania. + - Tested 7 principles with N=28,000 LLM conversations - Compliance increased 33% → 72% with persuasion techniques - Authority, commitment, scarcity most effective