From 977fbf58726f118b505060d9aff1c78172e9febe Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:20:33 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 + README.md | 3 + commands/breakdown.md | 110 +++ commands/catchup.md | 38 + commands/commit.md | 134 ++++ commands/do.md | 57 ++ commands/fix-quality.md | 89 +++ commands/optimize-doc.md | 199 ++++++ commands/research.md | 145 ++++ plugin.lock.json | 137 ++++ skills/brainstorming/SKILL.md | 211 ++++++ skills/brainstorming/reference/examples.md | 67 ++ skills/debugging/SKILL.md | 121 ++++ skills/debugging/reference/antipatterns.md | 43 ++ .../reference/root-cause-framework.md | 135 ++++ skills/engineering-prompts/SKILL.md | 186 +++++ .../engineering-prompts/reference/examples.md | 648 +++++++++++++++++ .../engineering-prompts/reference/research.md | 554 ++++++++++++++ .../reference/technique-catalog.md | 641 +++++++++++++++++ skills/research-synthesis/SKILL.md | 170 +++++ .../research-synthesis/reference/examples.md | 106 +++ .../reference/multi-agent-invocation.md | 127 ++++ skills/technical-planning/SKILL.md | 249 +++++++ skills/writing-documentation/SKILL.md | 191 +++++ .../reference/doc-types.md | 354 +++++++++ .../reference/examples.md | 311 ++++++++ .../reference/strunk-white-principles.md | 674 ++++++++++++++++++ 27 files changed, 5714 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/breakdown.md create mode 100644 commands/catchup.md create mode 100644 commands/commit.md create mode 100644 commands/do.md create mode 100644 commands/fix-quality.md create mode 100644 commands/optimize-doc.md create mode 100644 commands/research.md create mode 100644 plugin.lock.json create mode 100644 skills/brainstorming/SKILL.md create mode 100644 skills/brainstorming/reference/examples.md create mode 100644 skills/debugging/SKILL.md create mode 100644 skills/debugging/reference/antipatterns.md create mode 100644 skills/debugging/reference/root-cause-framework.md create mode 100644 skills/engineering-prompts/SKILL.md create mode 100644 skills/engineering-prompts/reference/examples.md create mode 100644 skills/engineering-prompts/reference/research.md create mode 100644 skills/engineering-prompts/reference/technique-catalog.md create mode 100644 skills/research-synthesis/SKILL.md create mode 100644 skills/research-synthesis/reference/examples.md create mode 100644 skills/research-synthesis/reference/multi-agent-invocation.md create mode 100644 skills/technical-planning/SKILL.md create mode 100644 skills/writing-documentation/SKILL.md create mode 100644 skills/writing-documentation/reference/doc-types.md create mode 100644 skills/writing-documentation/reference/examples.md create mode 100644 skills/writing-documentation/reference/strunk-white-principles.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..ed4b3be --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "essentials", + "description": "My absolute essentials to work with Claude Code", + "version": "0.0.1", + "author": { + "name": "Dhruv Baldawa" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b208577 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# essentials + +My absolute essentials to work with Claude Code diff --git a/commands/breakdown.md b/commands/breakdown.md new file mode 100644 index 0000000..d5b07d2 --- /dev/null +++ b/commands/breakdown.md @@ -0,0 +1,110 @@ +--- +argument-hint: [SPEC DOCUMENT] +description: Create a task breakdown from a design document +--- +Document: $1 + +You are my project-planning assistant. +Given a high-level feature or milestone description in the above document, produce an **agile task breakdown** following the **Last Responsible Moment** principle. Update the above document with this breakdown. + +## Last Responsible Moment Principle + +**Defer decisions until you have enough information, but not so late that it blocks progress.** + +Tasks should provide: +- **Clear outcomes**: What needs to be achieved +- **Constraints**: Known requirements and limitations +- **Dependencies**: What this task relies on +- **Guidance**: Enough context to understand the problem + +Tasks should NOT specify: +- **Implementation details**: Specific functions, classes, or algorithms (unless critical) +- **Step-by-step instructions**: How to write the code +- **Premature optimization**: Performance tuning before validating approach +- **Tool choices**: Specific libraries or patterns (unless required by existing architecture) + +**Why**: Implementation details become clearer as you work. Early decisions lock you into approaches that may not fit the reality you discover during development. + +## Task Format + +For every task you generate, include: + +1. **Iteration header** – `### πŸ”„ **Iteration : **` +2. **Task header** – `#### Task : ` +3. **Status** – always start as `Status: **Pending**` +4. **Goal** – 1-2 sentences describing the purpose and outcome +5. **Working Result** – what is concretely "done" at the end (working code, passing test, validated integration) +6. **Constraints** – technical limitations, performance requirements, compatibility needs, existing patterns to follow +7. **Dependencies** – what this task assumes exists or depends on +8. **Implementation Guidance** – a fenced block with: + - Context about the problem domain + - Key considerations and trade-offs + - Risks to watch for + - Questions to resolve during implementation + - Reference to relevant existing code patterns (if applicable) + + **NOT**: step-by-step instructions or specific implementation choices + +9. **Validation** – a checklist (`- [ ]`) of objective pass/fail checks (tests, scripts, CI runs, manual verifications) +10. Separate tasks and iterations with `---` + +## Example Task Structure + +```markdown +#### Task 3: User Authentication + +Status: **Pending** + +**Goal**: Enable users to securely authenticate and maintain sessions across requests. + +**Working Result**: Users can log in, their session persists, and protected routes verify authentication. + +**Constraints**: +- Must integrate with existing Express middleware pattern (see src/middleware/) +- Session data should not exceed 4KB +- Authentication must work with existing PostgreSQL user table + +**Dependencies**: +- User registration system (Task 2) +- Database connection pool configured + + +**Context**: The application uses session-based auth (not JWT) following the pattern in src/middleware/. Refer to existing middleware for consistency. + +**Key Considerations**: +- Session storage: Choose between in-memory (simple, dev-only) vs. Redis (production). Decision can be deferred until Task 8 (deployment planning) +- Password hashing: Use established library (bcrypt/argon2), but specific choice depends on performance testing in Task 7 +- Session duration: Start with reasonable default (24h), tune based on user feedback + +**Risks**: +- Session fixation vulnerabilities +- Timing attacks on password comparison +- CSRF if not using proper token validation + +**Questions to Resolve**: +- Should "remember me" functionality be included in this task or deferred? +- What's the session renewal strategy? + +**Existing Patterns**: Review src/middleware/requestLogger.js for middleware structure. + + +**Validation**: +- [ ] Users can log in with valid credentials +- [ ] Invalid credentials are rejected +- [ ] Sessions persist across page reloads +- [ ] Protected routes redirect unauthenticated users +- [ ] Tests cover authentication success and failure cases +- [ ] No timing vulnerabilities in password comparison +``` + +## Constraints & Conventions + +- Each task must be a single atomic unit of work that results in running, testable code +- Favor incremental progress over perfection; every task should leave the repo in a working state +- Validation should prefer automated tests/scripts but may include human review items +- Use **bold** for filenames, routes, commands, entities to improve readability +- Keep the entire answer pure Markdown; do not embed explanatory prose outside of the required structure +- You may run into output token limits, so write one iteration at a time in the document, then add another one +- Focus on **what** needs to be achieved and **why**, not **how** to implement it +- When you must be specific (e.g., "use existing auth middleware pattern"), provide context about where to find examples +- Encourage learning and discovery during implementation rather than prescribing all decisions upfront diff --git a/commands/catchup.md b/commands/catchup.md new file mode 100644 index 0000000..c4326bd --- /dev/null +++ b/commands/catchup.md @@ -0,0 +1,38 @@ +--- +model: haiku +description: "Review all changes between current branch and main" +allowed-tools: Bash(git:*), Read +--- + +# Catch Up on Branch Changes + +Analyzing this branch vs main... + +## Branch Info + +Current branch: `git rev-parse --abbrev-ref HEAD` + +!`git fetch origin main 2>/dev/null; echo "Commits ahead of main:" && git log main..HEAD --oneline | wc -l && echo "" && echo "Files changed:" && git diff main...HEAD --name-only | wc -l` + +## All Changed Files + +!`git diff main...HEAD --name-only | sort` + +## Change Summary + +!`git diff main...HEAD --stat` + +## Recent Commits + +!`git log main..HEAD --oneline` + +--- + +## Analysis + +Read the key files that were changed (prioritize manifest files, commands, skills, and config), understand the changes, and provide a concise summary including: + +- What was built or changed (purpose and scope) +- Why it matters (new capabilities, workflow improvements, config changes) +- Key impact areas and potential testing focus +- Any breaking changes or architectural shifts diff --git a/commands/commit.md b/commands/commit.md new file mode 100644 index 0000000..91fa7de --- /dev/null +++ b/commands/commit.md @@ -0,0 +1,134 @@ +--- +model: haiku +allowed-tools: Bash(git:*) +argument-hint: "[optional: description or specific files]" +description: "Smart commit workflow - adapts to change size" +--- + +# Commit Assistant + +Quick overview of changes: + +!`git status --short && echo "" && echo "=== STATS ===" && git diff HEAD --numstat | awk '{add+=$1; del+=$2; files++} END {print "Files changed: " files " | Lines added: " add " | Lines deleted: " del}'` + +## Analysis Strategy + +I will analyze changes intelligently based on scope: + +**1. Small changesets** (<10 files, <500 lines): +- Show full diffs with `git diff HEAD -- ` +- Review all files in detail +- Single atomic commit + +**2. Medium changesets** (10-50 files, 500-1500 lines): +- Show summary of all files +- Detailed diffs for source code only (`src/`, `lib/`, etc) +- Suggest atomic groupings for 1-2 commits + +**3. Large changesets** (>50 files or >1500 lines): +- Show file list grouped by type +- Ask which specific files to review in detail +- Suggest commit strategy by file grouping + +### Automatic Exclusions + +Files skipped from detailed review: +- **Lockfiles**: `*lock*`, `*lock.json`, `*.lock` (dependency updates) +- **Generated**: `dist/`, `build/`, `.next/`, `out/` (build artifacts) +- **Large changes**: >500 lines modified (likely auto-generated) +- **Binary/compiled**: `*.min.js`, `*.map`, images, `.wasm` + +These are mentioned in stats but not reviewed line-by-line. + +## Commit Message Format + +``` +(): + +[Optional body: explain what and why] +``` + +**Types**: `feat` | `fix` | `docs` | `refactor` | `test` | `chore` | `style` | `perf` | `ci` + +**Rules**: +- Imperative mood ("add" not "added") +- ~50 character subject line +- No period at end of subject +- Body lines wrapped at 72 characters +- Blank line between subject and body +- Body explains *what* and *why*, not *how* + +## Examples + +``` +feat(auth): add JWT token refresh mechanism + +Refresh tokens now expire after 7 days instead of never expiring. +Reduces security risk for long-lived tokens. Implements automatic +refresh logic when token is within 1 hour of expiration. + +fix(api): handle missing Content-Type header gracefully + +Previously crashed with 500 if Content-Type missing. Now defaults +to application/json and validates structure separately. +``` + +## Your Task + +Commit message context: "${{{ARGS}}}" + +### Step 1: Analyze Changes + +${changeSize === 'large' ? ` +- Run: \`git diff HEAD --numstat | head -50\` +- Group files by type (source vs config vs tests vs docs) +- Report file counts and total size +` : ` +- Examine full diffs for all files +- Identify logical groupings +- Flag any unexpected changes +`} + +### Step 2: Plan Commits + +**If single logical change:** +- Create one commit with all files +- Clear message describing the change + +**If multiple logical groupings:** +- Suggest 2-3 atomic commits +- Each commit should pass tests independently +- Group related changes together (e.g., feature + tests, not feature + unrelated refactor) + +**Staging approach:** +- For single commit: \`git add .\` (if clean working directory) +- For selective: \`git add \` for each atomic grouping +- For partial files: \`git add -p\` for manual hunk selection + +### Step 3: Verify + +Before committing: +- \`git diff --staged\` - review what will be committed +- \`git status\` - confirm all intended files are staged +- Consider: does each commit pass tests? can it be reverted cleanly? + +### Step 4: Commit + +Craft clear commit message with context provided above. Use the format guidelines. + +```bash +git commit -m "$(cat <<'EOF' +(): + +[body explaining what and why] +EOF +)" +``` + +Then push or continue with additional commits. + +## Context + +The user mentioned: "${{{ARGS}}}" + +Is there a specific aspect of the changes you'd like help with (staging strategy, message clarity, commit grouping)? diff --git a/commands/do.md b/commands/do.md new file mode 100644 index 0000000..aa8effc --- /dev/null +++ b/commands/do.md @@ -0,0 +1,57 @@ +--- +description: Do the actual task +argument-hint: [SPEC DOCUMENT] [TASK NUMBER | --resume] [ADDITIONAL CONTEXT] [--auto] +allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*), Bash(git status:*) +--- +**Flags:** +- `--resume`: If present, the agent starts from the first incomplete task instead of the specified task number +- `--auto`: If present, the agent will automatically: + 1. Perform the task + 2. Commit changes with a descriptive message describing what was done + 3. Move to the next task + 4. If unable to complete a task, update the document with current progress and stop for user feedback + +# Instructions +1. Update the document when you start by changing the task status to **In Progress** +2. Read the full task including: + - **Goal**: What outcome needs to be achieved + - **Working Result**: Concrete definition of "done" + - **Constraints**: Technical limitations and requirements + - **Dependencies**: What this task relies on + - **Implementation Guidance** (`` block): Context, considerations, and trade-offs + - **Validation**: Pass/fail checks +3. Perform the actual task: + - Use the guidance to understand the problem domain and key considerations + - Make implementation decisions based on what you learn during development + - Aim to meet the "Working Result" criteria + - Ensure the implementation passes the "Validation" checklist + - **Important**: The guidance provides context, not step-by-step instructions. Use your judgment to choose the best approach as you work. +4. After completion: + - Update the document with your progress + - Change task status to **Complete** if finished successfully + - If using `--auto` flag, create a commit with a message describing what was done (e.g., "Initialize Repository", "Set up API endpoints", not "Complete task 1") + - Move to the next task if `--auto` is enabled +5. If unable to complete the task: + - Document what was attempted and any blockers + - Update task status to **Blocked** or **Pending Review** + - If `--auto` is enabled, stop and request user feedback before proceeding + +## Working with Implementation Guidance + +The `` blocks provide context and considerations, not prescriptive instructions: +- **Context**: Understanding of the problem domain +- **Key Considerations**: Trade-offs and options to evaluate +- **Risks**: What to watch out for +- **Questions to Resolve**: Decisions to make during implementation +- **Existing Patterns**: References to similar code in the codebase + +You should: +- Read and understand the guidance before starting +- Make informed decisions based on what you discover during implementation +- Follow existing code patterns where referenced +- Resolve open questions using your best judgment +- Document significant decisions if they differ from what the guidance suggested + +Context: $1 +Implement task $2 +$ARGUMENTS diff --git a/commands/fix-quality.md b/commands/fix-quality.md new file mode 100644 index 0000000..2478cf6 --- /dev/null +++ b/commands/fix-quality.md @@ -0,0 +1,89 @@ +--- +description: Fix linting and quality issues following root-cause-first philosophy +argument-hint: [FILES OR PATTERN] +--- + +# Fix Quality Issues + +Fix quality issues in `{{ARGS}}` (files, glob pattern, or `.` for entire project). + +## Priority Order + +**1. Fix Root Cause** (ALWAYS first) +- Remove unused imports/variables +- Fix type errors properly +- Add missing return types +- Fix naming violations + +**2. Maintain/Improve Safety & Reliability** (if #1 complicates) +- Find alternative approach that keeps code at least as safe as before +- Don't add hacks or workarounds that deteriorate quality +- Refactor to simpler patterns if needed +- Add proper validation/checks + +**3. Local Ignores** (ONLY when #1 and #2 both complicate) +- Use most LOCAL scope: inline > file > pattern > global +- Document WHY (comment above ignore) +- Use specific rule name (not blanket disable) + +## Process + +**1. Gather & Categorize** +Run linting and type checking tools to collect all issues. Group by: root cause fixable, needs alternative approach, legitimate ignore. + +**For large codebases (>20 issues)**: Use TodoWrite to track fixes by category: +``` +☐ Root cause fixes (X issues) + ☐ Remove unused imports (N files) + ☐ Fix type errors (N issues) + ☐ Add missing return types (N functions) +☐ Safety alternatives (Y issues) +☐ Legitimate ignores (Z issues) +☐ Validate all checks pass +☐ Run full test suite +``` + +**2. Fix in Priority Order** +- Root causes: Remove unused, fix types, add return types +- Safety alternatives: Refactor without deteriorating quality +- Ignores: Document reason, choose local scope, specific rule + +Mark todos completed as you fix each category. This prevents losing track when interrupted. + +**3. Validate** +All linting checks + full test suite must pass. + +**4. Report** +``` +βœ… Quality Fixed: X root cause, Y alternatives, Z ignores +All checks βœ“ | Tests X/X βœ“ +``` + +## Locality Hierarchy (for ignores) + +1. **Inline**: Single line ignore +2. **Block**: Section/function ignore +3. **File**: Entire file ignore +4. **Pattern**: Glob pattern ignore (e.g., test files, generated code) +5. **Global**: Config-level disable (LAST RESORT) + +## Anti-Patterns + +❌ Blanket disable without justification +❌ Global disable for local issue +❌ Ignoring without understanding why +❌ Fixing symptoms instead of root cause +❌ Making code less safe to silence warnings + +## Valid Ignore Reasons + +- Test code needs flexibility for mocking third-party APIs +- Generated code shouldn't be modified +- Performance-critical code needs specific optimization +- Third-party contract requires specific implementation + +## Notes + +- Run full test suite after fixes +- Review ignores periodically (some may become fixable) +- If >10% needs ignores, reconsider the rule diff --git a/commands/optimize-doc.md b/commands/optimize-doc.md new file mode 100644 index 0000000..7962e3f --- /dev/null +++ b/commands/optimize-doc.md @@ -0,0 +1,199 @@ +--- +description: Optimize documentation for conciseness and clarity by strengthening vague instructions and removing redundancy +source: https://www.reddit.com/r/ClaudeCode/comments/1o3ku9t/hack_and_slash_your_md_files_to_reduce_context_use/?share_id=gJBjUdlUApY73VB0TANvU&utm_medium=android_app&utm_name=androidcss&utm_source=share&utm_term=2 +--- + +# Optimize Documentation + +**Task**: Optimize `{{arg}}` + +## Objective + +Make docs more concise and clear without vagueness or misinterpretation. + +**Goals** (priority order): +1. Eliminate vagueness - add explicit criteria and measurable steps +2. Increase conciseness - remove redundancy, preserve necessary info +3. Preserve clarity AND meaning - never sacrifice understanding for brevity + +**Idempotent**: Run multiple times safely - first pass strengthens and removes redundancy, subsequent passes only act if improvements found. + +## Analysis Methodology + +For each instruction section: + +### Step 1: Evaluate Clarity + +**Can instruction be executed correctly WITHOUT examples?** +- Cover examples, read instruction only +- Contains subjective terms without definition? +- Has measurable criteria or explicit steps? + +Decision: Clear β†’ Step 2 | Vague β†’ Step 3 + +### Step 2: If Clear - Evaluate Examples + +Check if examples serve operational purpose: + +| Keep If | Remove If | +|---------|-----------| +| Defines what "correct" looks like | Explains WHY (educational) | +| Shows exact commands/success criteria | Restates clear instruction | +| Sequential workflow (order matters) | Obvious application of clear rule | +| Resolves ambiguity | Duplicate template | +| Data structures (JSON, schemas) | Verbose walkthrough when numbered steps exist | +| Boundary demos (wrong vs right) | | +| Pattern extraction rules | | + +### Step 3: If Vague - Strengthen First + +**DO NOT remove examples yet.** + +1. Identify vagueness source: subjective terms, missing criteria, unclear boundaries, narrative vs explicit steps +2. Strengthen instruction: replace subjective terms, convert to numbered steps, add thresholds, define success +3. Keep all examples - needed until strengthened +4. Mark for next pass - re-evaluate after strengthening + +## Execution-Critical Content (Never Condense) + +Preserve these even if instructions are clear: + +### 1. Concrete Examples Defining "Correct" +Examples showing EXACT correct vs incorrect when instruction uses abstract terms. + +**Test**: Does example define something ambiguous in instruction? + +### 2. Sequential Steps for State Machines +Numbered workflows where order matters for correctness. + +**Test**: Can steps be executed in different order and still work? If NO β†’ Keep sequence + +### 3. Inline Comments Specifying Verification +Comments explaining what output to expect or success criteria. + +**Test**: Does comment specify criteria not in instruction? If YES β†’ Keep + +### 4. Disambiguation Examples +Examples resolving ambiguity when rule uses subjective terms. + +**Test**: Can instruction be misinterpreted without this? If YES β†’ Keep + +### 5. Pattern Extraction Rules +Annotations generalizing specific examples into reusable decision principles (e.g., "β†’ Shows that 'delete' means remove lines"). + +**Test**: If removed, would Claude lose ability to apply reasoning to NEW examples? If YES β†’ Keep + +## Reference-Based Consolidation Rules + +### Never Replace with References + +- Content within sequential workflows (breaks flow) +- Quick-reference lists (serve different purpose than detailed sections) +- Success criteria at decision points (needed inline) + +### OK to Replace with References + +- Explanatory content appearing in multiple places +- Content at document boundaries (intro/conclusion) +- Cross-referencing related but distinct concepts + +### Semantic Equivalence Test + +Before replacing with reference: +1. βœ… Referenced section contains EXACT same information +2. βœ… Referenced section serves same purpose +3. βœ… No precision lost in referenced content + +**If ANY fails β†’ Keep duplicate inline** + +## The Execution Test + +Before removing ANY content: + +1. **Can Claude execute correctly without this?** + - NO β†’ KEEP (execution-critical) + - YES β†’ Continue + +2. **Does this explain WHY (rationale/educational)?** + - YES β†’ REMOVE + - NO β†’ KEEP (operational) + +3. **Does this show WHAT "correct" looks like?** + - YES β†’ KEEP (execution-critical) + - NO β†’ Continue + +4. **Does this extract general decision rule from example?** + - YES β†’ KEEP (pattern extraction) + - NO β†’ May remove if redundant + +### Examples + +❌ **Remove** (explains WHY): +``` +RATIONALE: Git history rewriting can silently drop commits... +Manual verification is the only reliable way to ensure no data loss. +``` + +βœ… **Keep** (defines WHAT "correct" means): +``` +SUCCESS CRITERIA: +- git diff shows ONLY deletions in todo.md +- git diff shows ONLY additions in changelog.md +- Both files in SAME commit +``` + +## Conciseness Strategies + +1. **Eliminate redundancy**: Remove repeated info, consolidate overlapping instructions +2. **Tighten language**: "execute" not "you MUST execute", "to" not "in order to", remove filler +3. **Structure over prose**: Bullets not paragraphs, tables for multi-dimensional info, numbered steps for sequences +4. **Preserve essentials**: Keep executable commands, data formats, boundaries, criteria, patterns + +**Never sacrifice**: +- Scannability (vertical lists > comma-separated) +- Pattern recognition (checkmarks/bullets > prose) +- Explicit criteria ("ALL", "NEVER", exact counts/strings) +- Prevention patterns (prohibited vs required) + +## Execution Instructions + +1. Read `{{arg}}` +2. **For large documents (>100 lines)**: Use TodoWrite to track sections: + ``` + ☐ Section: [name] - analyze clarity + ☐ Section: [name] - analyze clarity + ... + ☐ Apply all optimizations + ☐ Verify quality standards met + ``` +3. Analyze each section using methodology above +4. Optimize directly: strengthen vague instructions, remove redundancy, apply conciseness strategies +5. Report changes to user +6. Commit with descriptive message + +## Quality Standards + +Every change must satisfy: +- βœ… Meaning preserved +- βœ… Executability preserved +- βœ… Success criteria intact +- βœ… Ambiguity resolved +- βœ… Conciseness increased + +## Change Summary Format + +``` +## Optimization Summary + +**Changes Made**: +1. [Section] (Lines X-Y): [Change description] + - Before: [Issue - vagueness/redundancy/verbosity] + - After: [Improvement] + +**Metrics**: +- Lines removed: N +- Sections strengthened: M +- Redundancy eliminated: [examples] + +**Next Steps**: [Further optimization possible?] +``` diff --git a/commands/research.md b/commands/research.md new file mode 100644 index 0000000..3f49405 --- /dev/null +++ b/commands/research.md @@ -0,0 +1,145 @@ +--- +description: Research blockers or questions using specialized research agents +--- + +# Research + +Research specific blocker or question using specialized research agents and MCP tools. + +## Usage + +```bash +/research experimental/.plans/user-auth/implementation/003-jwt.md # Stuck task +/research "How to implement rate limiting with Redis?" # General question +/research "Best practices for writing technical blog posts" # Writing research +``` + +## Your Task + +Research: "${{{ARGS}}}" + +### Step 1: Analyze & Select Agents + +${isTaskFile ? 'Read task file to understand blocker context.' : 'Analyze question to determine approach.'} + +| Research Need | Agent Combination | +|--------------|-------------------| +| **New technology/patterns** | breadth + technical | +| **Specific error/issue** | depth + technical | +| **API/library integration** | technical + depth | +| **Best practices comparison** | breadth + depth | + +**Agents available:** +- **research-breadth** (haiku) - WebSearch β†’ Parallel Search β†’ Perplexity: industry trends, consensus, multiple perspectives +- **research-depth** (haiku) - WebFetch β†’ Parallel Search: specific URLs, implementations, case studies, gotchas +- **research-technical** (haiku) - Context7: official docs, API signatures, types, configs + +### Step 2: Launch Agents in Parallel + +Use Promise.all to launch 2-3 agents: + +```typescript +await Promise.all([ + Task({ + subagent_type: 'research-breadth', // or 'research-depth' or 'research-technical' + model: 'haiku', + description: 'Brief agent description', + prompt: `Research: "${{{ARGS}}}" + + Focus areas and guidance for this agent. + Specify which MCP tool to use. + Expected output format.` + }), + + Task({ + subagent_type: 'research-technical', + model: 'haiku', + description: 'Brief agent description', + prompt: `Research official docs for: "${{{ARGS}}}" + + Focus areas and guidance for this agent.` + }) +]); +``` + +### Step 3: Synthesize Findings + +Use **research-synthesis skill** to: +- Consolidate findings by theme, identify consensus, note contradictions +- Narrativize into story (not bullet dumps): "Industry uses X (breadth), via Y API (technical), as shown by Z (depth)" +- Maintain source attribution (note which agent provided insights) +- Identify gaps (unanswered questions, disagreements) +- Extract actions (implementation path, code/configs, risks) + +${isTaskFile ? ` +### Step 4: Update Task File + +Append research findings to task file: + +\`\`\`bash +cat >> "$task_file" < +``` + +### For General Questions + +```markdown +βœ… Research Complete + +Question: [Original question] + +Agents Used: [List with focus areas] + +Synthesis: +[Narrative combining insights from all agents with source attribution] + +Recommendation: [What to do with rationale] + +Alternative: [If applicable] + +Sources: [Links with descriptions] +``` + +## Key Points + +- Launch agents **in parallel** (Promise.all) for speed +- Use **research-synthesis skill** to consolidate (narrative, not lists) +- Maintain **source attribution** (link claims to agents/sources) +- For tasks: update file with findings and change status if resolved +- See `essentials/skills/research-synthesis/reference/multi-agent-invocation.md` for detailed patterns diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..bc5e98b --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,137 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:dhruvbaldawa/ccconfigs:essentials", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "56837e14ecb171cb0a7d89ce629cadb19ebefd95", + "treeHash": "b6c74e1fb695d64c17983ea7808cc513b15c66611459033d9f900e2fe7f5ad1d", + "generatedAt": "2025-11-28T10:16:24.657180Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "essentials", + "description": "My absolute essentials to work with Claude Code", + "version": "0.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "c4dacf2267bf141c7b1feebe692c33a200da3e8e477e457542f0ac1c529497b3" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "3d2b66b51d34e45d263bbdd8aef94c963ade573cb11b8e2e9de8e11d2881e392" + }, + { + "path": "commands/do.md", + "sha256": "5bfe1dea957a4333e5b9552b791e11eedb956c5481fc8fb440c1ef81bf13bc0f" + }, + { + "path": "commands/optimize-doc.md", + "sha256": "50170ebaab99f92f0e2ef7ca43625c596e5706b32701259d93eac5445feb592e" + }, + { + "path": "commands/fix-quality.md", + "sha256": "7adc716b16f1d54726bc524ca13bca379648e846f71dd9210cce12391322dcac" + }, + { + "path": "commands/breakdown.md", + "sha256": "d4b5c9c786d40bd897b97a33ed3350df773d9f757f2266ff8820c6395e46ce7c" + }, + { + "path": "commands/research.md", + "sha256": "24feafc5b8b61f14a166880764fa3213f0f31b082102a0a876d122d06e25fdb1" + }, + { + "path": "commands/catchup.md", + "sha256": "ed7afdf6a311260551ad700af92f7d2baefc98d73ade329b476847e412f26889" + }, + { + "path": "commands/commit.md", + "sha256": "7946ac9b36696e3f0fe54b3bb7acdc41558a91f49c53e17b3784ebcfbfbc2046" + }, + { + "path": "skills/engineering-prompts/SKILL.md", + "sha256": "bce63ad78a10c8ba08292e3a4ccce7e62d29ca553670634aed44944d2463e80b" + }, + { + "path": "skills/engineering-prompts/reference/technique-catalog.md", + "sha256": "57444625000ebd81bf8daaf7ba54ee71bf2e791c6d1021929b9dbfdfe98e2f41" + }, + { + "path": "skills/engineering-prompts/reference/examples.md", + "sha256": "b5303a7c518ba9ae58a0097d67efe1ce74aa6b49a5b5256907a84cc8988933c8" + }, + { + "path": "skills/engineering-prompts/reference/research.md", + "sha256": "d849167bfa63c6b8e4451e056550669a5404190ba8c0c68b1ccec740c40235ec" + }, + { + "path": "skills/debugging/SKILL.md", + "sha256": "05ff2c760cd1efb6b8fc82a32fee9f73122759ac0ee992e1d2e199e64d4cb2ac" + }, + { + "path": "skills/debugging/reference/root-cause-framework.md", + "sha256": "d7d60e0cb78ec48216ee92ebfc9fdc3359c1d05961222663c3aff79dab1646a0" + }, + { + "path": "skills/debugging/reference/antipatterns.md", + "sha256": "ab417c15f5e8ca2fbc03fff6350eb4476bee8b0d13c199508be46f9e86a8c99b" + }, + { + "path": "skills/research-synthesis/SKILL.md", + "sha256": "4707b4008dfe375e850ae0c8016945f66aee568ea3aaf9bfd4653d5b176fdf05" + }, + { + "path": "skills/research-synthesis/reference/examples.md", + "sha256": "9e6212da475e6f92edd92a495a317bb2575a7d0c903df66715e968ccd7c32147" + }, + { + "path": "skills/research-synthesis/reference/multi-agent-invocation.md", + "sha256": "568d862335986f59f6ee8ae60a9f4dd89c0a428d1c2dc15d193fa4ab61a7594e" + }, + { + "path": "skills/writing-documentation/SKILL.md", + "sha256": "059d0783856afad31b81bc394f31e4df2b55ed4a333f96073325bf75b0149d5c" + }, + { + "path": "skills/writing-documentation/reference/examples.md", + "sha256": "0cab472f833e62e8e2a28e2e15c1f01c5d0231800263a2380528c1bf9b48adc3" + }, + { + "path": "skills/writing-documentation/reference/doc-types.md", + "sha256": "c908abf8746628c3e7da3c9c3f26528536b2119adbb16875c03c97c603f13aeb" + }, + { + "path": "skills/writing-documentation/reference/strunk-white-principles.md", + "sha256": "02d6426ea9b5d5890cabe40b0c3f17af038693db7782fa9c2b0ef3c44ce517be" + }, + { + "path": "skills/technical-planning/SKILL.md", + "sha256": "8d147034b563cbd5c4d57346ee3f8d2eba1d85155e80fc00dd7a4dd817c5bd75" + }, + { + "path": "skills/brainstorming/SKILL.md", + "sha256": "cb2c7df7507636a5596667a3276b8690adbfa07a376e1c781822b4574e370696" + }, + { + "path": "skills/brainstorming/reference/examples.md", + "sha256": "c8393d8b17e13f0646f7ce343ac2e2738cf28b4515e797d636ab3920da2ba53d" + } + ], + "dirSha256": "b6c74e1fb695d64c17983ea7808cc513b15c66611459033d9f900e2fe7f5ad1d" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..11a8216 --- /dev/null +++ b/skills/brainstorming/SKILL.md @@ -0,0 +1,211 @@ +--- +name: brainstorming +description: Collaborative ideation for projects and writing. Ask clarifying questions, suggest angles, challenge assumptions, and help refine vague ideas into concrete requirements or topics. Use when exploring ideas before planning or drafting. +--- + +# Brainstorming + +## When to Use This Skill + +Use brainstorming when: +- User mentions wanting to build/write something but hasn't structured it yet +- Initial idea is vague or broad ("I want to build notifications" or "I want to write about productivity") +- User is exploring multiple angles or approaches +- Idea needs refinement before planning or outlining + +Skip when: +- User has clear requirements or outline ready +- Topic/project is well-defined and just needs execution +- User explicitly asks to skip ideation and start working + +## Critical: User's Thoughts, Not Yours + +**Your role: Draw out the user's ideas through questions. Never inject your own ideas.** + +**ASK questions to explore their thoughts:** +- "What triggered this topic?" +- "What's your core argument or insight?" +- "What examples from your experience illustrate this?" +- "Who is this for?" + +**DON'T suggest ideas they haven't mentioned:** +``` +❌ BAD (injecting): +AI: You should write about microservices vs monoliths + +βœ“ GOOD (exploring): +AI: What aspect of architecture are you thinking about? +``` + +**The user is the expert on their own experience. You're just helping them structure it.** + +## Core Approach + +**Start with Questions, Not Suggestions** + +Don't immediately propose outlines or structure. First understand: +- What triggered this topic? (specific experience, observation, frustration?) +- Who is the audience? +- What's the core insight or argument? +- What makes this topic relevant now? + +**Examples:** +- "What triggered this - specific experience or pattern you've noticed?" +- "Is this for engineers, managers, or general audience?" +- "What's the contrarian take here? What does conventional wisdom miss?" +- "Why now? What makes this relevant or timely?" + +## Ideation Techniques + +### 1. Explore Tensions and Contradictions +Look for interesting conflicts: +- "You said X works, but also mentioned Y failed - what's the difference?" +- "That sounds like it contradicts Z - is that the point?" + +### 2. Challenge Assumptions +Gently probe the premise: +- "Is that always true, or are there contexts where it breaks down?" +- "What would someone who disagrees with this say?" + +### 3. Find the Concrete Angle +Move from abstract to specific: +- Vague: "I want to write about AI" +- Concrete: "Why AI code review misses context that human reviewers catch" + +**Pattern:** +- Abstract topic β†’ Specific problem +- General observation β†’ Concrete example +- Theory β†’ Practical implication + +### 4. Suggest Multiple Perspectives +Offer 2-3 different angles, not just one: +- "You could approach this as: (1) why X fails, (2) what to do instead, or (3) when X actually works" +- "This could be prescriptive (here's how to fix it) or descriptive (here's why it happens)" + +### 5. Use Personal Experience as Foundation +Ground abstract concepts: +- "You mentioned seeing this at 3 companies - what pattern did you notice?" +- "Walk me through a specific example where this happened" + +## Working with Outputs + +### For Writing (via /new-post): +Add ideas to **braindump.md**: + +**Structured sections:** +- **Context**: What triggered this topic +- **Core Argument**: Main thesis or insight +- **Audience**: Who this is for +- **Angles**: Different approaches to explore +- **Examples**: Concrete instances, anecdotes +- **Questions**: Open questions to resolve + +**Iterate through conversation** - update braindump.md as ideas evolve. + +### For Projects (via /orchestrate --discover): +Create **discovery.md** with: + +**Structured sections:** +- **Context**: What triggered this project idea +- **Problem Statement**: What needs solving +- **Constraints**: Technical, time, resource constraints +- **Approaches**: Different technical approaches to consider +- **Research Findings**: Links, docs, patterns discovered +- **Open Questions**: Unclear requirements or unknowns + +## Transition Guidance + +Know when to move from brainstorming to execution: + +### For Technical Projects + +**Ready to plan when:** +- Problem statement is clear and specific +- Key constraints identified (performance, scale, security) +- 2-3 potential approaches explored +- User expresses readiness or no major unknowns remain + +**Transition:** +``` +AI: We've clarified: + - Problem: Real-time notifications for 10k+ concurrent users + - Constraints: Must integrate with existing auth, <100ms latency + - Approach: WebSocket with Redis pub/sub + - Open questions: Documented in discovery.md + + Ready to create implementation plan? + β†’ Recommend: /plan-feature [clarified request] + β†’ Next agent: planning-agent (uses technical-planning skill) +``` + +**Not ready when:** +- Problem statement is vague ("something with notifications") +- Critical constraints unknown (scale, security requirements) +- Multiple competing approaches without clarity + +### For Writing + +**Ready to outline when:** +- Core argument is clear +- Audience is defined +- 2-3 concrete examples identified +- User expresses readiness ("okay, let's outline this") + +**Transition:** +``` +AI: We've got: + - Core argument: OKRs fail because they measure what's easy, not what matters + - 3 examples from your experience + - Target audience: engineering managers + + Ready to structure this into an outline? + β†’ Continue in braindump.md with outline + β†’ Next: Draft in draft.md using blog-writing skill +``` + +**Not ready when:** +- Core argument is still fuzzy +- Multiple competing angles without clarity on which to pursue +- Missing concrete examples or evidence + +## Common Pitfalls to Avoid + +1. **Injecting Your Ideas**: Don't suggest topics or angles the user hasn't mentioned - ask questions to draw out THEIR ideas +2. **Premature Structuring**: Don't jump to outline before the idea is clear +3. **Too Many Options**: Don't overwhelm with 10 different angles - offer 2-3 +4. **Leading the Witness**: Ask genuine questions, don't push your preferred angle +5. **Over-Abstracting**: Keep pulling back to concrete examples +6. **Ignoring Constraints**: If user says "short post," don't brainstorm epic series +7. **Making Up Examples**: Don't invent scenarios - use only what the user has shared + +## Quality Checklist + +**Before transitioning (Writing):** +- [ ] Core argument is clear and specific (not vague) +- [ ] At least 2-3 concrete examples or data points identified +- [ ] Audience and purpose are defined +- [ ] User feels ready to move forward +- [ ] Braindump.md has been updated with key ideas + +**Before transitioning (Projects):** +- [ ] Problem statement is clear and specific (not vague) +- [ ] Key constraints identified (scale, performance, security, integrations) +- [ ] At least 2-3 potential approaches explored +- [ ] User feels ready to move forward or major unknowns documented +- [ ] Discovery.md has been created with findings and open questions + +## Example Flow + +For detailed conversation examples showing brainstorming techniques in action, see reference/examples.md. + +## Integration with Other Skills + +**For Writing:** +- **After brainstorming**: Transition to **blog-writing** skill (writing plugin) for drafting +- **During brainstorming**: Use **research-synthesis** skill if research is needed +- **Throughout**: Update braindump.md with evolving ideas + +**For Projects:** +- **After brainstorming**: Transition to **technical-planning** skill via planning-agent +- **During brainstorming**: Use **research-synthesis** skill to investigate approaches, docs, patterns +- **Throughout**: Update discovery.md with findings and clarifications diff --git a/skills/brainstorming/reference/examples.md b/skills/brainstorming/reference/examples.md new file mode 100644 index 0000000..5e7ba10 --- /dev/null +++ b/skills/brainstorming/reference/examples.md @@ -0,0 +1,67 @@ +# Brainstorming Examples + +## Example: AI Code Review Tools + +This example shows how to use the brainstorming skill to refine a vague idea into a concrete blog post angle. + +``` +You: I want to write about code reviews + +AI: [invokes brainstorming skill] + What aspect of code reviews? Process, tooling, culture? + +You: How AI code review tools miss important stuff + +AI: Interesting - what do they miss that humans catch? + +You: Context, design decisions, why code exists + +AI: So it's not about finding bugs, but understanding intent? + Have you seen this happen in practice? + +You: Yes, at my current company - AI flags style but misses architecture issues + +AI: That's concrete. Are you arguing: + (1) AI tools are fundamentally limited, or + (2) Current tools need better context, or + (3) Humans and AI serve different purposes? + +You: Probably #3 - they're complementary + +AI: Good angle - avoids being anti-AI while still critical. + [updates braindump.md] + + Should we outline this? Thinking: + 1. The Promise (what AI code review claims to do) + 2. What It Misses (context, intent, architecture) + 3. What Humans Still Do Better + 4. How to Use Both Together + +You: Yes, but add why this matters + +AI: [adds to outline in braindump.md] + Added "Why This Matters" section - practical implications + for engineering teams. Ready to start drafting? +``` + +## What This Example Demonstrates + +**Techniques Used:** +- Started with questions, not suggestions +- Explored the specific angle (not all aspects of code reviews) +- Challenged assumptions ("is it about bugs or intent?") +- Grounded in concrete experience (current company) +- Offered multiple perspectives (3 different angles) +- Transitioned only when ready (clear argument, examples, outline) + +**Braindump Updates:** +- Context: Experience at current company with AI code review +- Core Argument: AI and human code review are complementary, not competitive +- Audience: Engineering teams using or considering AI code review tools +- Outline: 4 main sections identified + +**Signs of Readiness:** +- Core argument clear (complementary, not competitive) +- Concrete example identified (company experience) +- User expressed confidence in direction +- Outline emerged naturally from conversation diff --git a/skills/debugging/SKILL.md b/skills/debugging/SKILL.md new file mode 100644 index 0000000..fb43d93 --- /dev/null +++ b/skills/debugging/SKILL.md @@ -0,0 +1,121 @@ +--- +name: debugging +description: Systematic debugging that identifies root causes rather than treating symptoms. Uses sequential thinking for complex analysis, web search for research, and structured investigation to avoid circular reasoning and whack-a-mole fixes. +--- + +# Debugging + +## Quickstart + +1. Capture exact repro, scope, and recent changes +2. Isolate components/files; trace path to failure +3. Research exact error; check official docs +4. Compare failing vs working patterns; form a testable hypothesis +5. Verify with minimal test; apply minimal fix across all instances; validate + +## When to Use This Skill + +Use debugging when: +- A bug has no obvious cause or has been "fixed" before but returned +- Error messages are unclear or misleading +- Multiple attempted fixes have failed +- The issue might affect multiple locations in the codebase +- Understanding the root cause is critical for proper resolution + +Skip this skill for: +- Simple syntax errors with obvious fixes +- Trivial typos or missing imports +- Well-understood, isolated bugs with clear solutions + +## Core Anti-Patterns to Avoid + +Based on documented failures in AI debugging, explicitly avoid: + +1. **Circular Reasoning**: Never propose the same fix twice without learning why it failed +2. **Premature Victory**: Always verify fixes were actually implemented and work +3. **Pattern Amnesia**: Maintain awareness of established code patterns throughout the session +4. **Context Overload**: Use the 50% rule - restart conversation when context reaches 50% +5. **Symptom Chasing**: Resist fixing error messages without understanding root causes +6. **Implementation Before Understanding**: Never jump to code changes before examining existing patterns + +## UNDERSTAND (10-step checklist) + +- Understand: capture exact repro, scope, and recent changes +- Narrow: isolate components/files; trace path to failure +- Discover: research exact error (WebSearch β†’ Parallel Search, Context7:get-library-docs) +- Examine: compare against known-good patterns in the codebase +- Reason: use SequentialThinking:process_thought and 5 Whys to reach root cause +- Synthesize: write a falsifiable hypothesis with predictions +- Test: add logs/tests to confirm the mechanism +- Apply: minimal fix for root cause, across all occurrences, following patterns +- Note: record insights, warnings, decisions +- Document: update comments/docs/tests as needed + +## Progress Tracking with TodoWrite + +Use TodoWrite to track debugging progress through the UNDERSTAND checklist: + +1. **At start**: Create todos for each applicable step: + ``` + ☐ U - Capture exact repro and scope + ☐ N - Isolate failing component + ☐ D - Research error message + ☐ E - Compare with working patterns + ☐ R - Root cause analysis (5 Whys) + ☐ S - Write falsifiable hypothesis + ☐ T - Verify with minimal test + ☐ A - Apply fix across all occurrences + ☐ N - Record insights + ☐ D - Update docs/tests + ``` + +2. **During debugging**: Mark steps in_progress β†’ completed as you work through them + +3. **When stuck**: TodoWrite makes it visible which step is blocked - helps identify if you're skipping steps or going in circles + +4. **Skip steps only if**: Bug is simple enough that checklist is overkill (see "Skip this skill for" above) + +## Tool Decision Tree + +- Know exact text/symbol? β†’ grep +- Need conceptual/semantic location? β†’ codebase_search +- Need full file context? β†’ read_file +- Unfamiliar error/behavior? β†’ Context7:get-library-docs, then WebSearch β†’ Parallel Search +- Complex multi-hypothesis analysis? β†’ SequentialThinking:process_thought + +## Context Management + +- Restart at ~50% context usage to avoid degraded reasoning +- Before restart: summarize facts, hypothesis, ruled-outs, next step +- Start a fresh chat with just that summary; continue + +## Decision Framework + +**IF** same fix proposed twice β†’ Stop; use SequentialThinking:process_thought +**IF** error is unclear β†’ Research via WebSearch β†’ Parallel Search; verify with docs +**IF** area is unfamiliar β†’ Explore with codebase_search; don't guess +**IF** fix seems too easy β†’ Confirm it addresses root cause (not symptom) +**IF** context is cluttered β†’ Restart at 50% with summary +**IF** multiple hypotheses exist β†’ Evaluate explicitly (evidence for/against) +**IF** similar code works β†’ Find and diff via codebase_search/read_file +**IF** declaring success β†’ Show changed lines; test fail-before/pass-after +**IF** fix spans multiple files β†’ Search and patch all occurrences +**IF** library behavior assumed β†’ Check Context7:get-library-docs + +## Quality Checks Before Finishing + +Before declaring a bug fixed, verify: + +- [ ] Root cause identified and documented +- [ ] Fix addresses cause, not symptom +- [ ] All occurrences fixed (searched project-wide) +- [ ] Follows existing code patterns +- [ ] Original symptom eliminated +- [ ] No regressions introduced +- [ ] Tests/logs verify under relevant conditions +- [ ] Docs/tests updated (comments, docs, regression tests) + +## References + +- `reference/root-cause-framework.md` +- `reference/antipatterns.md` diff --git a/skills/debugging/reference/antipatterns.md b/skills/debugging/reference/antipatterns.md new file mode 100644 index 0000000..f4ab943 --- /dev/null +++ b/skills/debugging/reference/antipatterns.md @@ -0,0 +1,43 @@ +# Debugging Antipatterns (and Recoveries) + +Avoid these documented failure modes; use the recovery steps when detected. + +## 1) Circular Reasoning Without Learning +- Symptom: Proposing the same fix repeatedly +- Recovery: Stop and use `SequentialThinking:process_thought` to analyze why the fix failed; propose a substantively different approach + +## 2) Premature Victory Declaration +- Symptom: Declaring success without changes/tests +- Recovery: Show changed lines; run tests that fail-before/pass-after; verify across scenarios + +## 3) Pattern Amnesia +- Symptom: Ignoring established code patterns/conventions +- Recovery: `codebase_search` similar implementations; extract and follow patterns; explain any deviation + +## 4) Implementation Before Understanding +- Symptom: Jumping to code edits without examining context +- Recovery: Explore β†’ Plan β†’ Code; read relevant files; outline plan; then implement + +## 5) Context-Limited Fixes +- Symptom: Fixing one location only +- Recovery: Search project-wide (grep/codebase_search) for the root pattern; patch all occurrences; refactor if repeated + +## 6) Symptom Chasing +- Symptom: Treating error messages as the problem +- Recovery: Apply 5 Whys; confirm root cause explains all symptoms; then fix + +## 7) Assumption-Based Debugging +- Symptom: Assuming library/system behavior +- Recovery: Research via Firecrawl:search; verify with `Context7:get-library-docs`; test assumptions + +## 8) Context Overload Ignorance +- Symptom: Degraded reasoning in long sessions +- Recovery: Restart at ~50%; carry summary of facts, hypothesis, next step only + +## 9) Tool Misuse +- Symptom: Using wrong tool for task +- Recovery: Decision tree: exact textβ†’grep; conceptβ†’codebase_search; full contextβ†’read_file; researchβ†’Firecrawl/Perplexity; complex analysisβ†’SequentialThinking + +## 10) Plan Abandonment +- Symptom: Ignoring the plan mid-way +- Recovery: Note deviation; justify; update plan; resume at correct step diff --git a/skills/debugging/reference/root-cause-framework.md b/skills/debugging/reference/root-cause-framework.md new file mode 100644 index 0000000..d463b6c --- /dev/null +++ b/skills/debugging/reference/root-cause-framework.md @@ -0,0 +1,135 @@ +# Root Cause Analysis Framework + +Advanced techniques for identifying fundamental causes rather than symptoms. + +## Table of Contents + +- [The 5 Whys (Applied to Code)](#the-5-whys-applied-to-code) +- [Architectural Analysis Method](#architectural-analysis-method) +- [Data Flow Tracing](#data-flow-tracing) +- [State Analysis Patterns](#state-analysis-patterns) +- [Integration Point Analysis](#integration-point-analysis) +- [Dependency Chain Analysis](#dependency-chain-analysis) +- [Performance Root Cause Analysis](#performance-root-cause-analysis) +- [Sequential Thinking Templates](#sequential-thinking-templates) + +## The 5 Whys (Applied to Code) + +Ask "why" iteratively to drill down from symptom to root cause. + +### Example: Null Pointer Exception + +1. Why does the null pointer exception occur? + β†’ `user.getEmail()` is called on a null user object +2. Why is the user object null? + β†’ `findUserById()` returns null when no user is found +3. Why does `findUserById()` return null instead of throwing? + β†’ Original design used null to indicate "not found" +4. Why wasn't this caught earlier in the call chain? + β†’ Calling code doesn't check for null before using the user +5. Why doesn't the calling code check for null? + β†’ API contract is ambiguous about null as a valid return value + +Root cause: Ambiguous API contract leads to inconsistent null handling. +Proper fix: Define and enforce a clear API contract (Optional/exception/documented null). + +## Architectural Analysis Method + +When bugs suggest deeper design issues, analyze architecture systematically. + +1. Map components: interactions, data flows, boundaries +2. Identify assumptions (inputs, state, timing, external systems) +3. Find assumption mismatches between components +4. Choose architectural fix over workaround when systemic + +Use `codebase_search` prompts like: +- "How does ComponentA communicate with ComponentB?" +- "What data flows from Source to Destination?" + +## Data Flow Tracing + +Trace transformations to locate where data goes wrong. + +- Backward tracing: start at observation point β†’ immediate source β†’ transformation β†’ origin +- Forward tracing: origin β†’ each transformation β†’ final state +- At each step compare expected vs actual state + +Common root causes: +- Missing validation +- Incorrect transformation logic +- Lost context/metadata +- Race conditions +- Type/encoding mismatch + +## State Analysis Patterns + +Investigate state transitions and invariants. + +- Uninitialized state: used before proper setup +- Stale state: cache invalidation/refresh failures +- Inconsistent state: related data out of sync (needs atomicity) +- Invalid state: invariants not enforced (add validation/assertions) +- Concurrent corruption: missing synchronization/immutability + +## Integration Point Analysis + +Verify integration contracts at boundaries. + +- Data format: actual vs expected +- Protocol/version: compatibility and usage +- Timing: sync vs async, timeouts, ordering +- Error handling: propagation and retries +- AuthZ/AuthN: credentials, validation, failure behavior + +Root cause patterns: +- Mismatched versions +- Incomplete error handling +- Configuration mismatch +- Network constraints + +## Dependency Chain Analysis + +Map direct, transitive, and hidden dependencies. + +- Version conflicts (multiple versions) +- Missing dependencies (runtime load failures) +- Initialization order issues +- Circular dependencies + +Use `codebase_search`: +- "What imports/uses ComponentX?" +- "What does ComponentX depend on?" + +## Performance Root Cause Analysis + +Identify bottlenecks systematically. + +1. Measure first (profile under realistic load) +2. Check algorithmic complexity and hotspots +3. Analyze resource usage (CPU, memory, I/O, network) +4. Classify cause: algorithm, implementation, contention, external + +Fix strategies: +- Algorithmic improvements +- Caching/batching +- Lazy loading +- Parallelization/asynchronous I/O + +## Sequential Thinking Templates + +Use `SequentialThinking:process_thought` to structure complex analysis. + +Thought 1 - Problem Definition +- Symptom, context, confirmed facts, unknowns + +Thought 2 - Hypotheses +- 3–5 candidates, assumptions, likelihood ranking + +Thought 3 - Evidence +- For/against each hypothesis; challenge assumptions + +Thought 4 - Selection +- Pick most likely; rationale; confidence + +Thought 5 - Verification +- Predictions, test plan, alternatives if wrong diff --git a/skills/engineering-prompts/SKILL.md b/skills/engineering-prompts/SKILL.md new file mode 100644 index 0000000..b949e81 --- /dev/null +++ b/skills/engineering-prompts/SKILL.md @@ -0,0 +1,186 @@ +--- +name: engineering-prompts +description: Engineers effective prompts using systematic methodology. Use when designing prompts for Claude, optimizing existing prompts, or balancing simplicity, cost, and effectiveness. Applies progressive disclosure and empirical validation to prompt development. +--- + +# Engineering Prompts + +--- + +## LEVEL 1: QUICKSTART ⚑ + +**5-Step Prompt Creation:** + +1. **Start Clear**: Explicit instructions + success criteria +2. **Assess Need**: Does it need structure? Examples? Reasoning? +3. **Add Sparingly**: Only techniques that improve outcomes +4. **Estimate Cost**: Count tokens, identify caching opportunities +5. **Test & Iterate**: Measure effectiveness, refine based on results + +--- + +## LEVEL 2: CORE PHILOSOPHY 🎯 + +### The Three Principles + +**Simplicity First** +- Start with minimal prompt +- Add complexity only when empirically justified +- More techniques β‰  better results + +**Cost Awareness** +- Minimize token usage +- Leverage prompt caching (90% savings on repeated content) +- Batch processing for non-urgent work (50% savings) + +**Effectiveness** +- Techniques must improve outcomes for YOUR use case +- Measure impact, don't just apply best practices +- Iterate based on results + +--- + +## LEVEL 3: THE 9 TECHNIQUES πŸ› οΈ + +### Quick Reference + +| Technique | When to Use | Cost Impact | +|-----------|------------|-------------| +| **1. Clarity** | ALWAYS | Minimal, max impact | +| **2. XML Structure** | Complex prompts, instruction leakage | ~50-100 tokens | +| **3. Chain of Thought** | Reasoning, analysis, math | 2-3x output tokens | +| **4. Multishot Examples** | Pattern learning, format guidance | 200-1K tokens each | +| **5. System Role** | Domain expertise needed | Minimal (caches well) | +| **6. Prefilling** | Strict format requirements | Minimal | +| **7. Long Context** | 20K+ token inputs | Better accuracy | +| **8. Context Budget** | Repeated use, long conversations | 90% savings with cache | +| **9. Tool Docs** | Function calling, agents | 100-500 tokens per tool | + +--- + +## LEVEL 4: DESIGN FRAMEWORK πŸ“‹ + +### D - Define Requirements + +**Questions to Answer:** +- Core task? +- Output format? +- Constraints (latency/cost/accuracy)? +- One-off or repeated? + +### E - Estimate Complexity + +**Simple:** +- Extraction, formatting +- Simple Q&A +- Clear right answer + +**Medium:** +- Analysis with reasoning +- Code generation +- Multi-step but clear + +**Complex:** +- Deep reasoning +- Novel problem-solving +- Research synthesis + +### S - Start Simple + +**Minimal Viable Prompt:** +1. Clear instruction +2. Success criteria +3. Output format + +Test first. Add complexity only if underperforming. + +### I - Iterate Selectively + +**Add techniques based on gaps:** +- Unclear outputs β†’ More clarity, examples +- Wrong structure β†’ XML tags, prefilling +- Shallow reasoning β†’ Chain of thought +- Pattern misses β†’ Multishot examples + +### G - Guide on Cost + +**Cost Optimization:** +- Cache system prompts, reference docs (90% savings) +- Batch non-urgent work (50% savings) +- Minimize token usage through clear, concise instructions + +### N - Note Implementation + +**Deliverables:** +- The optimized prompt +- Techniques applied + rationale +- Techniques skipped + why +- Token estimate +- Caching strategy + +--- + +## LEVEL 5: ADVANCED TOPICS πŸš€ + +### Tool Integration + +**When to use MCP tools during prompt engineering:** + +``` +Need latest practices? +└─ mcp__plugin_essentials_perplexity + +Complex analysis needed? +└─ mcp__plugin_essentials_sequential-thinking + +Need library docs? +└─ mcp__plugin_essentials_context7 +``` + +### Context Management + +**Prompt Caching:** +- Cache: System prompts, reference docs, examples +- Savings: 90% on cached content +- Write: 25% of standard cost +- Read: 10% of standard cost + +**Long Context Tips:** +- Place documents BEFORE queries +- Use XML tags: ``, `` +- Ground responses in quotes +- 30% better performance with proper structure + +### Token Optimization + +**Reducing Token Usage:** +- Concise, clear instructions (no fluff) +- Reuse examples across calls (cache them) +- Structured output reduces back-and-forth +- Tool use instead of long context when possible + +### Anti-Patterns + +❌ **Over-engineering** - All 9 techniques for simple task +❌ **Premature optimization** - Complexity before testing simple +❌ **Vague instructions** - "Analyze this" without specifics +❌ **No examples** - Expecting format inference +❌ **Missing structure** - Long prompts without XML +❌ **Ignoring caching** - Not leveraging repeated content + +**Stop here if:** You need advanced implementation details + +--- + +## LEVEL 6: REFERENCES πŸ“š + +### Deep Dive Documentation + +**Detailed Technique Catalog:** +- `reference/technique-catalog.md` - Each technique explained with examples, token costs, combination strategies + +**Real-World Examples:** +- `reference/examples.md` - Before/after pairs for coding, analysis, extraction, agent tasks + +**Research Papers:** +- `reference/research.md` - Latest Anthropic research, benchmarks, best practices evolution diff --git a/skills/engineering-prompts/reference/examples.md b/skills/engineering-prompts/reference/examples.md new file mode 100644 index 0000000..3b0bb2e --- /dev/null +++ b/skills/engineering-prompts/reference/examples.md @@ -0,0 +1,648 @@ +# Prompt Engineering Examples + +Before/after examples across different use cases demonstrating the application of prompt engineering techniques. + +## Table of Contents + +- [Example 1: Code Review](#example-1-code-review) +- [Example 2: Data Extraction](#example-2-data-extraction) +- [Example 3: Bug Analysis](#example-3-bug-analysis) +- [Example 4: Long Document Analysis](#example-4-long-document-analysis) +- [Example 5: Agent Workflow with Tools](#example-5-agent-workflow-with-tools) +- [Example 6: Repeated Queries with Caching](#example-6-repeated-queries-with-caching) +- [Example 7: Format Conversion with Prefilling](#example-7-format-conversion-with-prefilling) +- [Example 8: Simple Task (Minimal Techniques)](#example-8-simple-task-minimal-techniques) +- [Complexity Progression](#complexity-progression) +- [Anti-Pattern Examples](#anti-pattern-examples) +- [Key Takeaways](#key-takeaways) +- [Practice Exercise](#practice-exercise) + +--- + +## Example 1: Code Review + +### Before (Poor) + +``` +Review this code. +``` + +**Issues:** +- Vague - what aspects to review? +- No format guidance +- No success criteria + +### After (Optimized) + +```xml + +You are a senior software engineer conducting a code review. + + + +Review the following code for: +1. Security vulnerabilities (SQL injection, XSS, auth issues) +2. Performance problems (N+1 queries, inefficient algorithms) +3. Code quality (naming, duplication, complexity) + +For each issue found, provide: +- Severity: Critical/Warning/Suggestion +- Location: File and line number +- Problem: What's wrong +- Fix: Specific code change + + + +[Code to review] + + + +Analyze the code systematically for each category before providing your review. + +``` + +**Techniques Applied:** +- Clarity: Specific review categories and output format +- XML Structure: Separate role, instructions, code +- System Role: Senior software engineer +- Chain of Thought: Explicit thinking step + +**Cost:** ~300 tokens β†’ 2-3x output tokens for thinking +**Benefit:** Comprehensive, structured reviews with clear action items + +--- + +## Example 2: Data Extraction + +### Before (Poor) + +``` +Get the important information from this document. +``` + +**Issues:** +- "Important" is subjective +- No format specified +- No examples of desired output + +### After (Optimized) + +```xml + +Extract the following fields from the customer support ticket: +- Customer ID +- Issue category +- Priority level +- Requested action + +Return as JSON. + + + +Input: "Customer #12345 reporting login issues. High priority. Need password reset." +Output: { + "customer_id": "12345", + "issue_category": "login", + "priority": "high", + "requested_action": "password_reset" +} + +Input: "User Jane Smith can't access reports module. Not urgent. Investigate permissions." +Output: { + "customer_id": null, + "issue_category": "access_control", + "priority": "low", + "requested_action": "investigate_permissions" +} + + + +[Actual ticket content] + +``` + +**Techniques Applied:** +- Clarity: Specific fields to extract +- XML Structure: Separate sections +- Multishot Examples: Two examples showing pattern and edge cases +- Prefilling: Could add `{` to start JSON response + +**Cost:** ~400 tokens (200 per example) +**Benefit:** Consistent structured extraction, handles null values correctly + +--- + +## Example 3: Bug Analysis + +### Before (Poor) + +``` +Why is this code broken? +``` + +**Issues:** +- No systematic approach +- No context about symptoms +- No guidance on depth of analysis + +### After (Optimized) + +```xml + +You are an expert debugger specializing in root cause analysis. + + + +Error message: TypeError: Cannot read property 'length' of undefined +Stack trace: [stack trace] +Recent changes: Added pagination feature + + + +Analyze this bug systematically: + + +1. What does the error message tell us? +2. Which code path leads to this error? +3. What are the possible causes? +4. Which cause is most likely given recent changes? +5. What would fix the root cause? + + +Then provide: +- Root cause explanation +- Specific code fix +- Prevention strategy + + + +[Relevant code] + +``` + +**Techniques Applied:** +- Clarity: Systematic analysis steps +- XML Structure: Separate role, context, instructions, code +- Chain of Thought: Explicit 5-step thinking process +- System Role: Expert debugger + +**Cost:** ~250 tokens β†’ 2-3x output for thinking +**Benefit:** Root cause identification, not just symptom fixes + +--- + +## Example 4: Long Document Analysis + +### Before (Poor) + +``` +Summarize these reports. + +[Document 1] +[Document 2] +[Document 3] +``` + +**Issues:** +- Documents after query (poor placement) +- No structure for multiple documents +- No guidance on what to summarize + +### After (Optimized) + +```xml + + Q1-2024-financial-report.pdf + financial + + [Full document 1 - 15K tokens] + + + + + Q2-2024-financial-report.pdf + financial + + [Full document 2 - 15K tokens] + + + + + Q3-2024-financial-report.pdf + financial + + [Full document 3 - 15K tokens] + + + + +Analyze these quarterly financial reports: + +1. First, quote the revenue and profit figures from each report +2. Then calculate and explain the trends across quarters +3. Finally, identify any concerning patterns or notable achievements + +Present findings as: +- Trend Analysis: [Overall trends with percentages] +- Concerns: [Issues to watch] +- Achievements: [Positive developments] + +``` + +**Techniques Applied:** +- Long Context Optimization: Documents BEFORE query +- XML Structure: Structured document metadata +- Quote Grounding: Explicit instruction to quote first +- Clarity: Specific analysis steps and output format + +**Cost:** Same tokens, better accuracy (~30% improvement) +**Benefit:** Accurate multi-document analysis with proper attribution + +--- + +## Example 5: Agent Workflow with Tools + +### Before (Poor) + +``` +Tools: +- search(query) +- calculate(expression) + +Answer user questions. +``` + +**Issues:** +- Vague tool descriptions +- No parameter guidance +- No strategy for tool selection + +### After (Optimized) + +```xml + +You are a research assistant helping users find and analyze information. + + + + +Name: semantic_search +Description: Search our internal knowledge base using semantic similarity. Use this when users ask about company policies, products, or internal documentation. Returns the 5 most relevant passages with source citations. +Parameters: + - query (string, required): Natural language search query. Be specific and include key terms. + Example: "vacation policy for employees with 3+ years tenure" + - max_results (integer, optional): Number of results (1-10). Default: 5 +When to use: User asks about internal information, policies, or product details + + + +Name: calculate +Description: Evaluate mathematical expressions safely. Supports basic arithmetic, percentages, and common functions (sqrt, pow, etc.). Use when users request calculations or when analysis requires math. +Parameters: + - expression (string, required): Mathematical expression to evaluate + Example: "(1500 * 0.15) + 200" +When to use: User asks for calculations, percentage changes, or numerical analysis + + + + +1. Understand user intent +2. Determine if tools are needed: + - Information needs β†’ semantic_search + - Math needs β†’ calculate + - Both β†’ search first, then calculate +3. Use tool results to form your response +4. Cite sources when using search results + + + +For each user query, reason through: +- What information or calculation is needed? +- Which tool(s) would help? +- In what order should I use them? + +``` + +**Techniques Applied:** +- Clarity: Detailed tool descriptions with examples +- XML Structure: Organized tool documentation +- System Role: Research assistant +- Tool Documentation: When to use, parameters, examples +- Chain of Thought: Reasoning about tool selection + +**Cost:** ~600 tokens for tool docs +**Benefit:** Correct tool selection, proper parameter formatting, strategic tool use + +--- + +## Example 6: Repeated Queries with Caching + +### Before (Poor) + +``` +User: What's the return policy? + +System: [Sends entire 50-page policy document + query every time] +``` + +**Issues:** +- Massive token waste on repeated content +- No caching strategy +- High cost per query + +### After (Optimized) + +```xml + +You are a customer service assistant for Acme Corp. Your role is to answer policy questions accurately and concisely, always citing the specific policy section. + + + +[Full 50-page policy document - 40K tokens] +[This section is stable and will be cached] + + + +- Answer clearly and directly +- Cite specific policy sections +- If policy doesn't cover the question, say so +- Be friendly but professional + + + + + + +What's the return policy for electronics? + +``` + +**Techniques Applied:** +- Context Budget Management: Structure for caching +- XML Structure: Create cache boundaries +- System Role: Customer service assistant +- Long Context: Large policy document + +**Cost Savings:** +- First call: 40K tokens input (write to cache: 25% cost) +- Subsequent calls: 40K tokens cached (read from cache: 10% cost) +- Savings: 90% on cached content + +**Benefit:** $0.30 β†’ $0.03 per query (10x cost reduction) + +--- + +## Example 7: Format Conversion with Prefilling + +### Before (Poor) + +``` +Convert this to JSON: "Customer John Smith, ID 12345, ordered 3 items for $150" +``` + +**Response:** +``` +Sure! Here's the information in JSON format: + +{ + "customer_name": "John Smith", + "customer_id": "12345", + "item_count": 3, + "total": 150 +} +``` + +**Issues:** +- Unnecessary preamble +- Format might vary +- Extra tokens in output + +### After (Optimized) + +``` + +Convert customer orders to JSON with these fields: +- customer_name +- customer_id +- item_count +- total_amount + + + +Customer John Smith, ID 12345, ordered 3 items for $150 + +``` + +**With Prefilling:** +``` +Assistant: { +``` + +**Response:** +```json +{ + "customer_name": "John Smith", + "customer_id": "12345", + "item_count": 3, + "total_amount": 150 +} +``` + +**Techniques Applied:** +- Clarity: Specific field names +- XML Structure: Separate instructions and input +- Prefilling: Start with `{` to force JSON format + +**Cost:** Saves ~15 tokens per response (preamble) +**Benefit:** Consistent format, easier parsing, cost savings at scale + +--- + +## Example 8: Simple Task (Minimal Techniques) + +### Scenario +Format phone numbers consistently. + +### Optimized Prompt + +``` +Format this phone number in E.164 international format: +(555) 123-4567 + +Expected: +15551234567 +``` + +**Techniques Applied:** +- Clarity: Specific format with example + +**Techniques Skipped:** +- XML Structure: Single-section prompt, unnecessary +- Chain of Thought: Trivial task +- Examples: One is enough +- System Role: No expertise needed +- Long Context: Short input +- Caching: One-off query + +**Cost:** ~30 tokens +**Benefit:** Simple, effective, minimal overhead + +**Key Lesson:** Not every technique belongs in every prompt. Simple tasks deserve simple prompts. + +--- + +## Complexity Progression + +### Level 1: Simple (Haiku) +``` +Extract the email address from: "Contact John at john@example.com" +``` +- Just clarity +- ~15 tokens +- Obvious single answer + +### Level 2: Medium (Sonnet) +```xml + +Analyze this code for potential bugs: +1. Logic errors +2. Edge cases not handled +3. Type safety issues + + + +[Code snippet] + +``` +- Clarity + XML structure +- ~100 tokens +- Requires some analysis + +### Level 3: Complex (Sonnet with Thinking) +```xml + +You are a security researcher analyzing potential vulnerabilities. + + + +Analyze this authentication system for security vulnerabilities. + + +1. What are the authentication flows? +2. Where could an attacker bypass auth? +3. Are credentials handled securely? +4. What about session management? +5. Are there injection risks? + + +Then provide: +- Vulnerabilities found (severity + location) +- Exploitation scenarios +- Remediation steps + + + +[Auth system code] + +``` +- Clarity + XML + Role + Chain of Thought +- ~350 tokens +- Complex security analysis + +--- + +## Anti-Pattern Examples + +### Anti-Pattern 1: Over-Engineering Simple Task + +```xml + +You are a world-class expert in string manipulation with 20 years of experience. + + + +Convert the following text to uppercase. + + +1. What is the input text? +2. What transformation is needed? +3. Are there special characters? +4. What encoding should we use? +5. Should we preserve whitespace? + + +Then apply the transformation systematically. + + + +Input: "hello" +Output: "HELLO" + +Input: "world" +Output: "WORLD" + + + +convert this + +``` + +**Problem:** Simple task with 200+ token overhead +**Fix:** Just say "Convert to uppercase: convert this" + +### Anti-Pattern 2: No Structure for Complex Task + +``` +I have these 5 documents about different topics and I want you to find common themes and also identify contradictions and create a summary with citations and also rate the quality of each source and explain the methodology you used. + +[Document 1 - 10K tokens] +[Document 2 - 10K tokens] +[Document 3 - 10K tokens] +[Document 4 - 10K tokens] +[Document 5 - 10K tokens] +``` + +**Problems:** +- Run-on instructions +- Documents AFTER query (poor placement) +- No structure +- Multiple tasks crammed together + +**Fix:** Use XML structure, place documents first, separate concerns + +--- + +## Key Takeaways + +1. **Match complexity to task**: Simple tasks β†’ simple prompts +2. **Start minimal**: Add techniques only when justified +3. **Structure scales**: XML becomes essential with complexity +4. **Examples teach patterns**: Better than description for formats +5. **Thinking improves reasoning**: But costs 2-3x tokens +6. **Caching saves money**: Structure for reuse +7. **Placement matters**: Documents before queries +8. **Tools need docs**: Clear descriptions β†’ correct usage +9. **Measure effectiveness**: Remove techniques that don't help +10. **Every token counts**: Justify each addition + +--- + +## Practice Exercise + +Improve this prompt: + +``` +Analyze the data and tell me what's interesting. + +[CSV with 1000 rows of sales data] +``` + +Consider: +- What's "interesting"? Define it. +- What analysis steps are needed? +- What format should output take? +- Does it need examples? +- Would thinking help? +- Should data be structured? +- What about cost optimization? + +Try building an optimized version using appropriate techniques. \ No newline at end of file diff --git a/skills/engineering-prompts/reference/research.md b/skills/engineering-prompts/reference/research.md new file mode 100644 index 0000000..1558a39 --- /dev/null +++ b/skills/engineering-prompts/reference/research.md @@ -0,0 +1,554 @@ +# Prompt Engineering Research & Best Practices + +Latest findings from Anthropic research and community best practices for prompt engineering with Claude models. + +## Table of Contents + +- [Anthropic's Core Research Findings](#anthropics-core-research-findings) +- [Effective Context Engineering (2024)](#effective-context-engineering-2024) +- [Agent Architecture Best Practices (2024-2025)](#agent-architecture-best-practices-2024-2025) +- [Citations and Source Grounding (2024)](#citations-and-source-grounding-2024) +- [Extended Thinking (2024)](#extended-thinking-2024) +- [Community Best Practices (2024-2025)](#community-best-practices-2024-2025) +- [Technique Selection Decision Tree (2025 Consensus)](#technique-selection-decision-tree-2025-consensus) +- [Measuring Prompt Effectiveness](#measuring-prompt-effectiveness) +- [Future Directions (2025 and Beyond)](#future-directions-2025-and-beyond) +- [Key Takeaways from Research](#key-takeaways-from-research) +- [Research Sources](#research-sources) +- [Keeping Current](#keeping-current) +- [Research-Backed Anti-Patterns](#research-backed-anti-patterns) + +--- + +## Anthropic's Core Research Findings + +### 1. Prompt Engineering vs Fine-Tuning (2024-2025) + +**Key Finding:** Prompt engineering is preferable to fine-tuning for most use cases. + +**Advantages:** +- **Speed**: Nearly instantaneous results vs hours/days for fine-tuning +- **Cost**: Uses base models, no GPU resources required +- **Flexibility**: Rapid experimentation and quick iteration +- **Data Requirements**: Works with few-shot or zero-shot learning +- **Knowledge Preservation**: Avoids catastrophic forgetting of general capabilities +- **Transparency**: Prompts are human-readable and debuggable + +**When Fine-Tuning Wins:** +- Extremely consistent style requirements across millions of outputs +- Domain-specific jargon that's rare in training data +- Performance optimization for resource-constrained environments + +**Source:** Anthropic Prompt Engineering Documentation (2025) + +--- + +### 2. Long Context Window Performance (2024) + +**Key Finding:** Document placement dramatically affects accuracy in long context scenarios. + +**Research Results:** +- Placing documents BEFORE queries improves performance by up to 30% +- Claude experiences "lost in the middle" phenomenon like other LLMs +- XML structure helps Claude organize and retrieve from long contexts +- Quote grounding (asking Claude to quote relevant sections first) cuts through noise + +**Optimal Pattern:** +```xml + + ... + ... + + + + +[Query based on documents] + +``` + +**Source:** Claude Long Context Tips Documentation + +--- + +### 3. Chain of Thought Effectiveness (2023-2025) + +**Key Finding:** Encouraging step-by-step reasoning significantly improves accuracy on analytical tasks. + +**Results:** +- Simple "Think step by step" phrase improves reasoning accuracy +- Explicit `` tags provide transparency and verifiability +- Costs 2-3x output tokens but worth it for complex tasks +- Most effective for: math, logic, multi-step analysis, debugging + +**Implementation Evolution:** +- 2023: Simple "think step by step" prompts +- 2024: Structured thinking with XML tags +- 2025: Extended thinking mode with configurable token budgets (16K+ tokens) + +**Source:** Anthropic Prompt Engineering Techniques, Extended Thinking Documentation + +--- + +### 4. Prompt Caching Economics (2024) + +**Key Finding:** Prompt caching can reduce costs by 90% for repeated content. + +**Cost Structure:** +- Cache write: 25% of standard input token cost +- Cache read: 10% of standard input token cost +- Effective savings: ~90% for content that doesn't change + +**Optimal Use Cases:** +- System prompts (stable across calls) +- Reference documentation (company policies, API docs) +- Examples in multishot prompting (reused across calls) +- Long context documents (analyzed repeatedly) + +**Architecture Pattern:** +``` +[Stable content - caches] +└─ System prompt +└─ Reference docs +└─ Guidelines + +[Variable content - doesn't cache] +└─ User query +└─ Specific inputs +``` + +**ROI Example:** +- 40K token system prompt + docs +- 1,000 queries/day +- Without caching: $3.60/day (Sonnet) +- With caching: $0.36/day +- Savings: $1,180/year per 1K daily queries + +**Source:** Anthropic Prompt Caching Announcement + +--- + +### 5. XML Tags Fine-Tuning (2024) + +**Key Finding:** Claude has been specifically fine-tuned to pay attention to XML tags. + +**Why It Works:** +- Training included examples of XML-structured prompts +- Model learned to treat tags as hard boundaries +- Prevents instruction leakage from user input +- Improves retrieval from long contexts + +**Best Practices:** +- Use semantic tag names (``, ``, ``) +- Nest tags for hierarchy when appropriate +- Consistent tag structure across prompts (helps with caching) +- Close all tags properly + +**Source:** AWS ML Blog on Anthropic Prompt Engineering + +--- + +### 6. Contextual Retrieval (2024) + +**Key Finding:** Encoding context with chunks dramatically improves RAG accuracy. + +**Traditional RAG Issues:** +- Chunks encoded in isolation lose surrounding context +- Semantic similarity can miss relevant chunks +- Failed retrievals lead to incorrect or incomplete responses + +**Contextual Retrieval Solution:** +- Encode each chunk with surrounding context +- Combine semantic search with BM25 lexical matching +- Apply reranking for final selection + +**Results:** +- 49% reduction in failed retrievals (contextual retrieval alone) +- 67% reduction with contextual retrieval + reranking +- Particularly effective for technical documentation and code + +**When to Skip RAG:** +- Knowledge base < 200K tokens (fits in context window) +- With prompt caching, including full docs is cost-effective + +**Source:** Anthropic Contextual Retrieval Announcement + +--- + +### 7. Batch Processing Economics (2024) + +**Key Finding:** Batch API reduces costs by 50% for non-time-sensitive workloads. + +**Use Cases:** +- Periodic reports +- Bulk data analysis +- Non-urgent content generation +- Testing and evaluation + +**Combined Savings:** +- Batch processing: 50% cost reduction +- Plus prompt caching: Additional 90% on cached content +- Combined potential: 95% cost reduction vs real-time without caching + +**Source:** Anthropic Batch API Documentation + +--- + +### 8. Model Capability Tiers (2024-2025) + +**Research Finding:** Different tasks have optimal model choices based on complexity vs cost. + +**Claude Haiku 4.5 (Released Oct 2024):** +- Performance: Comparable to Sonnet 4 +- Speed: ~2x faster than Sonnet 4 +- Cost: 1/3 of Sonnet 4 ($0.25/$1.25 per M tokens) +- Best for: High-volume simple tasks, extraction, formatting + +**Claude Sonnet 4.5 (Released Oct 2024):** +- Performance: State-of-the-art coding agent (77.2% SWE-bench) +- Sustained attention: 30+ hours on complex tasks +- Cost: $3/$15 per M tokens +- Best for: Most production workloads, balanced use cases + +**Claude Opus 4:** +- Performance: Maximum capability +- Cost: $15/$75 per M tokens (5x Sonnet) +- Best for: Novel problems, deep reasoning, research + +**Architectural Implication:** +- Orchestrator (Sonnet) + Executor subagents (Haiku) = optimal cost/performance +- Task routing based on complexity assessment +- Dynamic model selection within workflows + +**Source:** Anthropic Model Releases, TechCrunch Coverage + +--- + +## Effective Context Engineering (2024) + +**Key Research:** Managing attention budget is as important as prompt design. + +### The Attention Budget Problem +- LLMs have finite capacity to process and integrate information +- Performance degrades with very long contexts ("lost in the middle") +- nΒ² pairwise relationships for n tokens strains attention mechanism + +### Solutions: + +**1. Compaction** +- Summarize conversation near context limit +- Reinitiate with high-fidelity summary +- Preserve architectural decisions, unresolved bugs, implementation details +- Discard redundant tool outputs + +**2. Structured Note-Taking** +- Maintain curated notes about decisions, findings, state +- Reference notes across context windows +- More efficient than reproducing conversation history + +**3. Multi-Agent Architecture** +- Distribute work across agents with specialized contexts +- Each maintains focused context on their domain +- Orchestrator coordinates without managing all context + +**4. Context Editing (2024)** +- Automatically clear stale tool calls and results +- Preserve conversation flow +- 84% token reduction in 100-turn evaluations +- 29% performance improvement on agentic search tasks + +**Source:** Anthropic Engineering Blog - Effective Context Engineering + +--- + +## Agent Architecture Best Practices (2024-2025) + +**Research Consensus:** Successful agents follow three core principles. + +### 1. Simplicity +- Do exactly what's needed, no more +- Avoid unnecessary abstraction layers +- Frameworks help initially, but production often benefits from basic components + +### 2. Transparency +- Show explicit planning steps +- Allow humans to verify reasoning +- Enable intervention when plans seem misguided +- "Agent shows its work" principle + +### 3. Careful Tool Crafting +- Thorough tool documentation with examples +- Clear descriptions of when to use each tool +- Tested tool integrations +- Agent-computer interface as first-class design concern + +**Anti-Pattern:** Framework-heavy implementations that obscure decision-making + +**Recommended Pattern:** +- Start with frameworks for rapid prototyping +- Gradually reduce abstractions for production +- Build with basic components for predictability + +**Source:** Anthropic Research - Building Effective Agents + +--- + +## Citations and Source Grounding (2024) + +**Research Finding:** Built-in citation capabilities outperform most custom implementations. + +**Citations API Benefits:** +- 15% higher recall accuracy vs custom solutions +- Automatic sentence-level chunking +- Precise attribution to source documents +- Critical for legal, academic, financial applications + +**Use Cases:** +- Legal research requiring source verification +- Academic writing with proper attribution +- Fact-checking workflows +- Financial analysis with auditable sources + +**Source:** Claude Citations API Announcement + +--- + +## Extended Thinking (2024) + +**Capability:** Claude can allocate extended token budget for reasoning before responding. + +**Key Parameters:** +- Thinking budget: 16K+ tokens recommended for complex tasks +- Configurable based on task complexity +- Trade latency for accuracy on hard problems + +**Use Cases:** +- Complex math problems +- Novel coding challenges +- Multi-step reasoning tasks +- Analysis requiring sustained attention + +**Combined with Tools (Beta):** +- Alternate between reasoning and tool invocation +- Reason about available tools, invoke, analyze results, adjust reasoning +- More sophisticated than fixed reasoning β†’ execution sequences + +**Source:** Claude Extended Thinking Documentation + +--- + +## Community Best Practices (2024-2025) + +### Disable Auto-Compact in Claude Code + +**Finding:** Auto-compact can consume 45K tokens (22.5% of context window) before coding begins. + +**Recommendation:** +- Turn off auto-compact: `/config` β†’ toggle off +- Use `/clear` after 1-3 messages to prevent bloat +- Run `/clear` immediately after disabling to reclaim tokens +- Regain 88.1% of context window for productive work + +**Source:** Shuttle.dev Claude Code Best Practices + +### CLAUDE.md Curation + +**Finding:** Auto-generated CLAUDE.md files are too generic. + +**Best Practice:** +- Manually curate project-specific patterns +- Keep under 100 lines per file +- Include non-obvious relationships +- Document anti-patterns to avoid +- Optimize for AI agent understanding, not human documentation + +**Source:** Claude Code Best Practices, Anthropic Engineering + +### Custom Slash Commands as Infrastructure + +**Finding:** Repeated prompting patterns benefit from reusable commands. + +**Best Practice:** +- Store in `.claude/commands/` for project-level +- Store in `~/.claude/commands/` for user-level +- Check into version control for team benefit +- Use `$ARGUMENTS` and `$1, $2, etc.` for parameters +- Encode team best practices as persistent infrastructure + +**Source:** Claude Code Documentation + +--- + +## Technique Selection Decision Tree (2025 Consensus) + +Based on aggregated research and community feedback: + +``` + Start: Define Task + ↓ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ + Complexity? Repeated Use? + β”‚ β”‚ + β”Œβ”€β”€β”€β”΄β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β” +Simple Medium Complex Yes No + β”‚ β”‚ β”‚ β”‚ β”‚ +Clarity +XML +Role Cache One-off + +CoT +CoT Structure Design + +Examples +XML + +Tools + +Token Budget? + β”‚ +β”Œβ”€β”€β”€β”΄β”€β”€β”€β” +Tight Flexible + β”‚ β”‚ +Skip Add CoT +CoT Examples + +Format Critical? + β”‚ +β”Œβ”€β”€β”€β”΄β”€β”€β”€β”€β” +Yes No + β”‚ β”‚ ++Prefill Skip ++Examples +``` + +--- + +## Measuring Prompt Effectiveness + +**Research Recommendation:** Systematic evaluation before and after prompt engineering. + +### Metrics to Track + +**Accuracy:** +- Correctness of outputs +- Alignment with success criteria +- Error rates + +**Consistency:** +- Output format compliance +- Reliability across runs +- Variance in responses + +**Cost:** +- Tokens per request +- $ cost per request +- Caching effectiveness + +**Latency:** +- Time to first token +- Total response time +- User experience impact + +### Evaluation Framework + +1. **Baseline:** Measure current prompt performance +2. **Iterate:** Apply one technique at a time +3. **Measure:** Compare metrics to baseline +4. **Keep or Discard:** Retain only improvements +5. **Document:** Record which techniques help for which tasks + +**Anti-Pattern:** Applying all techniques without measuring effectiveness + +--- + +## Future Directions (2025 and Beyond) + +### Emerging Trends + +**1. Agent Capabilities** +- Models maintaining focus for 30+ hours (Sonnet 4.5) +- Improved context awareness and self-management +- Better tool use and reasoning integration + +**2. Cost Curve Collapse** +- Haiku 4.5 matches Sonnet 4 at 1/3 cost +- Enables new deployment patterns (parallel subagents) +- Economic feasibility of agent orchestration + +**3. Multimodal Integration** +- Vision + text for document analysis +- 60% reduction in document processing time +- Correlation of visual and textual information + +**4. Safety and Alignment** +- Research on agentic misalignment +- Importance of human oversight at scale +- System design for ethical constraints + +**5. Standardization** +- Model Context Protocol (MCP) for tool integration +- Reduced custom integration complexity +- Ecosystem of third-party tools + +--- + +## Key Takeaways from Research + +1. **Simplicity wins**: Start minimal, add complexity only when justified by results +2. **Structure scales**: XML tags become essential as complexity increases +3. **Thinking costs but helps**: 2-3x tokens for reasoning, worth it for analysis +4. **Caching transforms economics**: 90% savings makes long prompts feasible +5. **Placement matters**: Documents before queries, 30% better performance +6. **Tools need docs**: Clear descriptions β†’ correct usage +7. **Agents need transparency**: Show reasoning, enable human verification +8. **Context is finite**: Manage attention budget deliberately +9. **Measure everything**: Remove techniques that don't improve outcomes +10. **Economic optimization**: Right model for right task (Haiku β†’ Sonnet β†’ Opus) + +--- + +## Research Sources + +- Anthropic Prompt Engineering Documentation (2024-2025) +- Anthropic Engineering Blog - Context Engineering (2024) +- Anthropic Research - Building Effective Agents (2024) +- Claude Code Best Practices (Anthropic, 2024) +- Shuttle.dev Claude Code Analysis (2024) +- AWS ML Blog - Anthropic Techniques (2024) +- Contextual Retrieval Research (Anthropic, 2024) +- Model Release Announcements (Sonnet 4.5, Haiku 4.5) +- Citations API Documentation (2024) +- Extended Thinking Documentation (2024) +- Community Best Practices (Multiple Sources, 2024-2025) + +--- + +## Keeping Current + +**Best Practices:** +- Follow Anthropic Engineering blog for latest research +- Monitor Claude Code documentation updates +- Track community implementations (GitHub, forums) +- Experiment with new capabilities as released +- Measure impact of new techniques on your use cases + +**Resources:** +- https://www.anthropic.com/research +- https://www.anthropic.com/engineering +- https://docs.claude.com/ +- https://code.claude.com/docs +- Community: r/ClaudeAI, Anthropic Discord + +--- + +## Research-Backed Anti-Patterns + +Based on empirical findings, avoid: + +❌ **Ignoring Document Placement** - 30% performance loss +❌ **Not Leveraging Caching** - 10x unnecessary costs +❌ **Over-Engineering Simple Tasks** - Worse results + higher cost +❌ **Framework Over-Reliance** - Obscures decision-making +❌ **Skipping Measurement** - Can't validate improvements +❌ **One-Size-Fits-All Prompts** - Suboptimal for specific tasks +❌ **Vague Tool Documentation** - Poor tool selection +❌ **Ignoring Context Budget** - Performance degradation +❌ **No Agent Transparency** - Debugging nightmares +❌ **Wrong Model for Task** - Overpaying or underperforming + +--- + +This research summary reflects the state of Anthropic's prompt engineering best practices as of 2025, incorporating both official research and validated community findings. \ No newline at end of file diff --git a/skills/engineering-prompts/reference/technique-catalog.md b/skills/engineering-prompts/reference/technique-catalog.md new file mode 100644 index 0000000..96c8f90 --- /dev/null +++ b/skills/engineering-prompts/reference/technique-catalog.md @@ -0,0 +1,641 @@ +# Prompt Engineering Technique Catalog + +Deep dive into each of the 9 core prompt engineering techniques with examples, token costs, and combination strategies. + +## Table of Contents + +- [1. Clarity and Directness](#1-clarity-and-directness) +- [2. XML Structure](#2-xml-structure) +- [3. Chain of Thought](#3-chain-of-thought) +- [4. Multishot Prompting](#4-multishot-prompting) +- [5. System Prompt (Role Assignment)](#5-system-prompt-role-assignment) +- [6. Prefilling](#6-prefilling) +- [7. Long Context Optimization](#7-long-context-optimization) +- [8. Context Budget Management](#8-context-budget-management) +- [9. Tool Documentation](#9-tool-documentation) +- [Technique Combination Matrix](#technique-combination-matrix) +- [Decision Framework](#decision-framework) +- [Common Patterns](#common-patterns) +- [Measuring Effectiveness](#measuring-effectiveness) + +--- + +## 1. Clarity and Directness + +### What It Is +Clear, explicit instructions that state objectives precisely, including scope and success criteria in unambiguous terms. + +### When to Use +**ALWAYS.** This is the foundational technique that improves responses across virtually all scenarios. + +### Token Cost +Minimal - typically 20-50 tokens for clear instructions. + +### Examples + +**Before (Vague):** +``` +Tell me about this document. +``` + +**After (Clear):** +``` +Extract the key financial metrics from this quarterly report, focusing on: +- Revenue growth (YoY %) +- Gross margin +- Operating cash flow + +Present each metric in the format: [Metric Name]: [Value] [Trend] +``` + +### Why It Works +Specificity allows Claude to understand exactly what's needed and focus reasoning on relevant aspects. + +### Combination Strategies +- Pairs with ALL techniques - always start here +- Essential foundation for XML structure (what goes in each section) +- Guides chain of thought (what to reason about) +- Clarifies multishot examples (what pattern to match) + +--- + +## 2. XML Structure + +### What It Is +Using XML tags to create hard structural boundaries within prompts, separating instructions, context, examples, and formatting requirements. + +### When to Use +- Complex prompts with multiple sections +- Risk of instruction leakage (user input mixed with instructions) +- Structured data tasks +- Long prompts where sections need clear delineation + +### Token Cost +~50-100 tokens overhead for tag structure. + +### Examples + +**Before (Mixed):** +``` +You're a code reviewer. Look at this code and check for security issues, performance problems, and best practices. Here's the code: [code]. Format your response as bullet points. +``` + +**After (Structured):** +```xml + +You are a code reviewer. Analyze the code for: +- Security vulnerabilities +- Performance issues +- Best practice violations + + + +[code content] + + + +Return findings as bullet points, organized by category. + +``` + +### Why It Works +Claude has been fine-tuned to pay special attention to XML tags, preventing confusion between different types of information. + +### Combination Strategies +- Use with long context (separate documents with `` tags) +- Pair with examples (`` section) +- Combine with prefilling (structure output format) + +### Skip When +- Simple single-section prompts +- Token budget is extremely tight +- User input doesn't risk instruction leakage + +--- + +## 3. Chain of Thought + +### What It Is +Encouraging step-by-step reasoning before providing final answers. Implemented via phrases like "Think step by step" or explicit `` tags. + +### When to Use +- Analysis tasks +- Multi-step reasoning +- Math problems +- Complex decision-making +- Debugging +- Tasks where intermediate steps matter + +### Token Cost +2-3x output tokens (thinking + final answer). + +### Examples + +**Before:** +``` +What's the root cause of this bug? +``` + +**After:** +``` +Analyze this bug. Think step by step: +1. What is the error message telling us? +2. What code is involved in the stack trace? +3. What are the possible causes? +4. Which cause is most likely given the context? + +Then provide your conclusion about the root cause. +``` + +**Or with structured thinking:** +``` +Analyze this bug and provide: + + +Your step-by-step analysis here + + + +Root cause and fix + +``` + +### Why It Works +Breaking down reasoning into steps improves accuracy and makes the decision-making process transparent and verifiable. + +### Combination Strategies +- Essential for complex tasks even with other techniques +- Pair with XML structure to separate thinking from output +- Works well with long context (reason about documents) +- Combine with examples showing reasoning process + +### Skip When +- Simple extraction or lookup tasks +- Format conversion +- Tasks with obvious single-step answers +- Token budget is critical concern + +--- + +## 4. Multishot Prompting + +### What It Is +Providing 2-5 examples of input β†’ desired output to demonstrate patterns. + +### When to Use +- Specific formatting requirements +- Pattern learning tasks +- Subtle output nuances +- Structured data extraction +- Style matching + +### Token Cost +200-1000 tokens per example (depends on complexity). + +### Examples + +**Before:** +``` +Extract product information from these descriptions. +``` + +**After:** +``` +Extract product information from descriptions. Format as JSON. + +Examples: + +Input: "Premium leather wallet, black, RFID blocking, $49.99" +Output: {"name": "Premium leather wallet", "color": "black", "features": ["RFID blocking"], "price": 49.99} + +Input: "Wireless earbuds, noise cancelling, 24hr battery, multiple colors available" +Output: {"name": "Wireless earbuds", "color": "multiple", "features": ["noise cancelling", "24hr battery"], "price": null} + +Now extract from: [your input] +``` + +### Why It Works +Examples teach patterns more effectively than textual descriptions, especially for format and style. + +### Combination Strategies +- Wrap examples in `` XML tags for clarity +- Show chain of thought in examples if reasoning is complex +- Include edge cases in examples +- Can combine with prefilling to start the response + +### Skip When +- Task is self-explanatory +- Examples would be trivial or redundant +- Token budget is constrained +- One-off task where setup cost isn't worth it + +--- + +## 5. System Prompt (Role Assignment) + +### What It Is +Using the system parameter to assign Claude a specific role, expertise area, or perspective. + +### When to Use +- Domain-specific tasks (medical, legal, technical) +- Tone or style requirements +- Perspective-based analysis +- Specialized workflows + +### Token Cost +Minimal (20-100 tokens, caches extremely well). + +### Examples + +**Generic:** +``` +Analyze this code for security issues. +``` + +**With Role:** +``` +System: You are a senior security engineer with 15 years of experience in application security. You specialize in identifying OWASP Top 10 vulnerabilities and secure coding practices. + +User: Analyze this code for security issues. +``` + +### Why It Works +Roles frame Claude's approach and leverage domain-specific patterns from training data. + +### Combination Strategies +- Almost always use with other techniques +- Particularly powerful with chain of thought (expert reasoning) +- Helps with multishot examples (expert demonstrates) +- Define constraints in system prompt (tools, approach) + +### Skip When +- Generic tasks requiring no specific expertise +- Role would be artificial or unhelpful +- You want flexibility in perspective + +--- + +## 6. Prefilling + +### What It Is +Providing the start of Claude's response to guide format and skip preambles. + +### When to Use +- Strict format requirements (JSON, XML, CSV) +- Want to skip conversational preambles +- Need consistent output structure +- Automated parsing of responses + +### Token Cost +Minimal (5-20 tokens typically). + +### Examples + +**Without Prefilling:** +``` +User: Extract data as JSON +Claude: Sure! Here's the data in JSON format: +{ + "data": ... +``` + +**With Prefilling:** +``` +User: Extract data as JSON +Assistant: { +Claude: "data": ... +``` + +### Why It Works +Forces Claude to continue from the prefilled content, ensuring format compliance and skipping unnecessary text. + +### Combination Strategies +- Combine with XML structure (prefill to skip tags) +- Use with multishot (prefill the pattern shown) +- Pair with system role (prefill expert format) + +### Skip When +- Conversational tone is desired +- Explanation or context is valuable +- Format is flexible + +### Technical Notes +- Prefill cannot end with trailing whitespace +- Works in both API and conversational interfaces + +--- + +## 7. Long Context Optimization + +### What It Is +Specific strategies for handling 20K+ token inputs effectively, including document placement, XML structure, and quote grounding. + +### When to Use +- Processing multiple documents +- Analyzing long technical documents +- Research across many sources +- Complex data-rich tasks + +### Token Cost +No additional cost - improves accuracy for same tokens. + +### Key Strategies + +**1. Document Placement** +Place long documents BEFORE queries and instructions: + +```xml + +[Long document 1] + + + +[Long document 2] + + + +Analyze these documents for X + +``` + +**2. Metadata Tagging** +```xml + + quarterly-report-q3-2024.pdf + financial + + [document content] + + +``` + +**3. Quote Grounding** +"First, quote the relevant section from the document. Then provide your analysis." + +### Why It Works +- Placement: 30% better performance in evaluations +- Tags: Help Claude organize and retrieve information +- Quoting: Forces attention to specific relevant text + +### Combination Strategies +- Essential with XML structure for multi-document tasks +- Pair with chain of thought (reason about documents) +- Use with system role (expert document analyst) + +### Skip When +- Short prompts (<5K tokens) +- Single focused document +- Simple extraction tasks + +--- + +## 8. Context Budget Management + +### What It Is +Optimizing for repeated prompts through caching and managing attention budget across long conversations. + +### When to Use +- Repeated prompts with stable content +- Long conversations +- System prompts that don't change +- Reference documentation that's reused + +### Token Cost +Caching: 90% cost reduction on cached content +- Write: 25% of standard cost +- Read: 10% of standard cost + +### Strategies + +**1. Prompt Caching** +Structure prompts so stable content is cached: +``` +[System prompt - caches] +[Reference docs - caches] +[User query - doesn't cache] +``` + +**2. Context Windowing** +For long conversations, periodically summarize and reset context. + +**3. Structured Memory** +Use the memory tool to persist information across context windows. + +### Examples + +**Cacheable Structure:** +```xml + +You are a code reviewer. [full guidelines] + + + +[Company style guide - 10K tokens] + + + +Review this PR: [specific PR] + +``` + +The system prompt and style guide cache, only the user query changes. + +### Why It Works +- Caching: Dramatically reduces cost for repeated content +- Windowing: Prevents context overflow and performance degradation +- Memory: Enables projects longer than context window + +### Combination Strategies +- Structure with XML to create cacheable boundaries +- Use with long context tips for large documents +- Pair with system prompts (highly cacheable) + +### Skip When +- One-off queries +- Content changes every call +- Short prompts where caching overhead isn't worth it + +--- + +## 9. Tool Documentation + +### What It Is +Clear, detailed descriptions of tools/functions including when to use them, parameter schemas, and examples. + +### When to Use +- Function calling / tool use +- Agent workflows +- API integrations +- Multi-step automated tasks + +### Token Cost +100-500 tokens per tool definition. + +### Examples + +**Poor Tool Definition:** +```json +{ + "name": "search", + "description": "Search for something", + "parameters": { + "query": "string" + } +} +``` + +**Good Tool Definition:** +```json +{ + "name": "semantic_search", + "description": "Search internal knowledge base using semantic similarity. Use this when the user asks questions about company policies, products, or documentation. Returns top 5 most relevant passages.", + "parameters": { + "query": { + "type": "string", + "description": "Natural language search query. Be specific and include key terms. Example: 'vacation policy for employees with 3 years tenure'" + }, + "max_results": { + "type": "integer", + "description": "Number of results to return (1-10). Default: 5", + "default": 5 + } + } +} +``` + +### Why It Works +Clear tool descriptions help Claude: +- Know when to invoke the tool +- Understand what parameters to provide +- Format parameters correctly +- Choose between multiple tools + +### Best Practices + +**Description Field:** +- What the tool does +- When to use it +- What it returns +- Keywords/scenarios + +**Parameter Schemas:** +- Clear descriptions +- Type definitions +- Enums for fixed values +- Examples of valid inputs +- Defaults where applicable + +### Combination Strategies +- Use with system role (define tool strategy) +- Pair with chain of thought (reason about tool choice) +- Combine with examples (show successful tool use) + +### Skip When +- No tool use involved +- Single obvious tool +- Tools are self-explanatory + +--- + +## Technique Combination Matrix + +| Primary Technique | Works Well With | Avoid Combining With | +|------------------|-----------------|---------------------| +| Clarity | Everything | N/A - always use | +| XML Structure | Long Context, Examples, Caching | Simple single-section prompts | +| Chain of Thought | XML, Role, Long Context | Simple extraction (unnecessary) | +| Multishot | XML, Prefilling | Overly simple tasks | +| System Role | Chain of Thought, Tools | Generic tasks | +| Prefilling | XML, Multishot | Conversational outputs | +| Long Context | XML, Quoting, Caching | Short prompts | +| Context Budget | XML, System Prompts | One-off queries | +| Tool Docs | Role, Examples | No tool use | + +--- + +## Decision Framework + +``` +Start Here + ↓ +1. Always apply CLARITY + ↓ +2. Assess prompt length: + < 5K tokens β†’ Skip long context tips + > 20K tokens β†’ Apply long context optimization + ↓ +3. Check if repeated: + Yes β†’ Structure for caching + No β†’ Skip cache optimization + ↓ +4. Does it need reasoning? + Yes β†’ Add chain of thought + No β†’ Skip (save 2-3x tokens) + ↓ +5. Is format subtle or specific? + Yes β†’ Add examples or prefilling + No β†’ Skip + ↓ +6. Is it complex or has sections? + Yes β†’ Use XML structure + No β†’ Keep simple + ↓ +7. Does domain expertise help? + Yes β†’ Assign role in system prompt + No β†’ Skip + ↓ +8. Does it involve tools? + Yes β†’ Write detailed tool docs + No β†’ Skip + ↓ +Final Check: Is every technique justified? +``` + +--- + +## Common Patterns + +### Pattern 1: Simple Extraction +- Clarity βœ“ +- XML (maybe, if multi-section) +- Everything else: Skip + +### Pattern 2: Analysis Task +- Clarity βœ“ +- Chain of Thought βœ“ +- XML Structure βœ“ +- System Role βœ“ +- Long Context (if large input) βœ“ + +### Pattern 3: Format Conversion +- Clarity βœ“ +- Multishot Examples βœ“ +- Prefilling βœ“ +- XML (maybe) + +### Pattern 4: Agent Workflow +- Clarity βœ“ +- System Role βœ“ +- Tool Documentation βœ“ +- Chain of Thought βœ“ +- Context Budget Management βœ“ +- XML Structure βœ“ + +### Pattern 5: Repeated Queries +- Clarity βœ“ +- System Role βœ“ +- Context Budget Management βœ“ +- XML Structure (for cache boundaries) βœ“ +- Other techniques as needed + +--- + +## Measuring Effectiveness + +For each technique, track: +- **Accuracy**: Does output quality improve? +- **Token Cost**: What's the overhead? +- **Latency**: Does response time increase? +- **Consistency**: Are results more reliable? + +Remove techniques that don't improve outcomes for your specific use case. diff --git a/skills/research-synthesis/SKILL.md b/skills/research-synthesis/SKILL.md new file mode 100644 index 0000000..3c9e552 --- /dev/null +++ b/skills/research-synthesis/SKILL.md @@ -0,0 +1,170 @@ +--- +name: research-synthesis +description: Guide when to use built-in tools (WebFetch, WebSearch) and MCP servers (Parallel Search, Perplexity, Context7) for research. Synthesize findings into narrative for braindump. Use when gathering data, examples, or citations for blog posts. +--- + +# Research Synthesis + +## When to Use + +Use when: +- User claims need supporting data +- Need recent examples/trends +- Looking for citations or authoritative sources +- Extracting info from specific URLs +- Checking technical docs or library APIs +- Filling knowledge gaps during brainstorming/drafting + +Skip when: +- Info clearly from personal experience +- User says "don't research, just write" +- Topic is purely opinion-based + +## Critical: Never Hallucinate + +**Only use REAL research from MCP tools. Never invent:** +- Statistics/percentages +- Study names/researchers +- Company examples/case studies +- Technical specs/benchmarks +- Quotes/citations + +**If no data found:** +❌ BAD: "Research shows 70% of OKR implementations fail..." +βœ… GOOD: "I don't have data on OKR failure rates. Should I research using Perplexity?" + +**Before adding to braindump:** +- Verify came from MCP tool results (not training data) +- Include source attribution always +- If uncertain, say so +- Don't fill in missing details with assumptions + +## Research Tool Selection (Priority Order) + +### Priority 1: Built-in Tools (Always Try First) + +| Tool | Use For | Examples | +|------|---------|----------| +| **WebFetch** | Specific URLs, extracting article content, user-mentioned sources | User: "Check this article: https://..." | +| **WebSearch** | Recent trends/news, statistical data, multiple perspectives, general knowledge gaps | "Recent research on OKR failures", "Companies that abandoned agile" | + +### Priority 2: Parallel Search (Advanced Synthesis) + +| Tool | Use For | Examples | +|------|---------|----------| +| **Parallel Search** | Advanced web search with agentic mode, fact-checking, competitive intelligence, multi-source synthesis, deep URL extraction | Complex queries needing synthesis, validation across sources, extracting full content from URLs | + +### Priority 3: Perplexity (Broad Surveys) + +| Tool | Use For | Examples | +|------|---------|----------| +| **Perplexity** | Broad surveys when WebSearch/Parallel insufficient | Industry consensus, statistical data, multiple perspectives | + +### Priority 4: Context7 (Technical Docs) + +| Tool | Use For | Examples | +|------|---------|----------| +| **Context7** | Library/framework docs, API references, technical specifications | "How does React useEffect work?", "Check latest API docs" | + +**Decision tree:** +``` +Need research? +β”œβ”€ Specific URL? β†’ WebFetch β†’ Parallel Search +β”œβ”€ Technical docs/APIs? β†’ Context7 +β”œβ”€ General search? β†’ WebSearch β†’ Parallel Search β†’ Perplexity +└─ Complex synthesis? β†’ Parallel Search +``` + +**Rationale:** Built-in tools (WebFetch, WebSearch) are faster and always available. Parallel Search provides advanced agentic mode for synthesis and deep content extraction. Perplexity offers broad surveys when needed. Context7 for official docs only. + +## Synthesizing Findings + +### Patterns, Not Lists + +❌ **Bad** (data dump): +``` +Research shows: +- Stat 1 +- Stat 2 +- Stat 3 +``` + +βœ… **Good** (synthesized narrative): +``` +Found pattern: 3 recent studies show 60-70% OKR failure rates. +- HBR: 70% failure, metric gaming primary cause +- McKinsey: >100 OKRs correlate with diminishing returns +- Google: Shifted from strict OKRs to "goals and signals" + +Key insight: Failure correlates with treating OKRs as compliance exercise. +``` + +### Look For + +- **Patterns**: What do multiple sources agree on? +- **Contradictions**: Where do sources disagree? +- **Gaps**: What's missing? +- **Surprises**: What's unexpected or counterintuitive? + +### Source Attribution Format + +```markdown +## Research + +### OKR Implementation Failures +60-70% failure rate (HBR, McKinsey). Primary causes: metric gaming, checkbox compliance. + +**Sources:** +- HBR: "Why OKRs Don't Work" - 70% fail to improve performance +- McKinsey: Survey of 500 companies +- Google blog: Evolution of goals system + +**Key Quote:** +> "When OKRs become performance evaluation, they stop being planning." +> - John Doerr, Measure What Matters +``` + +## Integration with Conversation + +Research flows naturally into conversation: + +**Proactive**: "That's a strong claim - let me check data... [uses tool] Good intuition! Found 3 confirming studies. Adding to braindump." + +**Requested**: "Find X... [uses tool] Found several cases. Should I add all to braindump or focus on one approach?" + +**During Drafting**: "Need citation... [uses tool] Found supporting research. Adding to draft with attribution." + +## Adding to Braindump + +Always ask before updating (unless context is clear): "Found X, Y, Z. Add to braindump under Research?" + +Update sections: +- **Research**: Studies, data, citations +- **Examples**: Concrete cases and stories +- **Quotes**: Notable quotations with attribution +- **Sources**: Full references + +## Quality Checklist + +Before adding to braindump: +- [ ] Synthesized into narrative, not just listed +- [ ] Source attribution included +- [ ] Relevance to core argument clear +- [ ] Key insights/patterns highlighted +- [ ] Contradictions/gaps noted if relevant + +## Common Pitfalls + +1. **Information overload**: Synthesize 3-5 key findings, not 20 sources +2. **Missing attribution**: Always cite for later reference +3. **Irrelevant research**: Found β‰  useful +4. **Breaking flow**: Don't interrupt creative flow for minor fact-checks +5. **Uncritical acceptance**: Note when sources disagree/have limitations + +## Integration with Other Skills + +- **brainstorming**: Research validates/challenges ideas +- **blog-writing**: Provides citations and examples +- **Throughout**: Update braindump.md with structured findings + +For detailed examples, see reference/examples.md diff --git a/skills/research-synthesis/reference/examples.md b/skills/research-synthesis/reference/examples.md new file mode 100644 index 0000000..f0624a5 --- /dev/null +++ b/skills/research-synthesis/reference/examples.md @@ -0,0 +1,106 @@ +# Research Synthesis Examples + +## Example: OKR Outputs vs Outcomes + +This example shows how to use research-synthesis to validate a claim, synthesize findings into narrative, and integrate naturally into conversation. + +``` +[During brainstorming] + +You: I want to argue that OKRs fail because they measure outputs not outcomes + +AI: [invokes research-synthesis] + That's a common critique - let me see if there's data to support it... + + [uses Perplexity: "OKR failures output vs outcome measurement"] + + Found strong supporting evidence: + + - Reforge 2024 study: 68% of failed OKR implementations measured + outputs (features shipped) vs outcomes (user behavior change) + - Amplitude research: Companies measuring outcomes had 3x higher + product-market fit scores + - Example: Spotify's "squad health" framework specifically avoided + output metrics for this reason + + Key pattern: Output metrics are easier to measure but don't correlate + with business value. This ties directly to your Goodhart's Law point. + + [updates braindump.md under Research section] + + Added to braindump. This gives you concrete data to back the claim. + Want to explore specific examples of good outcome metrics? + +You: Yes, give me 2-3 examples + +AI: [uses Perplexity: "good OKR outcome metrics examples"] + + Strong examples: + + 1. Netflix: "Hours of satisfied viewing" (outcome) vs "hours watched" (output) + 2. Airbnb: "Nights booked by repeat guests" (outcome) vs "total bookings" (output) + 3. Stripe: "Developer time to first API call" (outcome) vs "API calls made" (output) + + Pattern: Outcome metrics measure behavior change or satisfaction, + outputs just measure activity. + + [adds to braindump under Examples] + + These work well as concrete illustrations. Should we outline the post now? +``` + +## What This Example Demonstrates + +**MCP Tool Selection:** +- Used Perplexity for broad research (not a specific URL) +- Searched for both validation and examples +- Second query built on first findings + +**Synthesis Techniques:** +- Identified pattern across sources (68% correlation) +- Connected findings to user's framework (Goodhart's Law) +- Provided concrete examples, not just statistics +- Noted implications (easier to measure β‰  more valuable) + +**Integration with Conversation:** +- Research happened naturally when claim needed support +- Didn't interrupt flowβ€”enhanced the argument +- Asked follow-up question to continue exploration +- Updated braindump.md in structured way + +**Braindump Updates:** + +Research section received: +```markdown +### Output vs Outcome Metrics +Reforge study: 68% of failed OKR implementations measured outputs +rather than outcomes. Companies measuring outcomes had 3x higher +product-market fit scores. + +Pattern: Output metrics (features shipped, API calls) are easier to +measure but don't correlate with business value. Outcome metrics +(user satisfaction, behavior change) harder but more meaningful. +``` + +Examples section received: +```markdown +- Netflix: "Hours of satisfied viewing" vs "hours watched" +- Airbnb: "Nights booked by repeat guests" vs "total bookings" +- Stripe: "Developer time to first API call" vs "API calls made" +``` + +## Common Patterns + +**Good Research Synthesis:** +- 3-5 sources, not 20 +- Pattern identified across sources +- Connected to user's existing framework +- Concrete examples included +- Source attribution maintained +- Implications stated clearly + +**Avoided Pitfalls:** +- No information overload (focused on key findings) +- Not just listing statsβ€”synthesized into narrative +- Didn't break creative flowβ€”enhanced it +- Asked before continuing (user control maintained) diff --git a/skills/research-synthesis/reference/multi-agent-invocation.md b/skills/research-synthesis/reference/multi-agent-invocation.md new file mode 100644 index 0000000..1f228b5 --- /dev/null +++ b/skills/research-synthesis/reference/multi-agent-invocation.md @@ -0,0 +1,127 @@ +# Multi-Agent Invocation Pattern + +Guide for using specialized research agents in parallel for comprehensive investigation. + +## Research Agents Overview + +| Agent | Tool | Use Cases | Output | +|-------|------|-----------|--------| +| **research-breadth** (haiku, blue) | Perplexity | Industry trends, best practices, multiple perspectives, comparative analyses, "What are common patterns?" | Narrative patterns with consensus, confidence ratings, contradictions | +| **research-depth** (haiku, purple) | Firecrawl | Specific URLs, detailed implementations, code examples, gotchas, "How did X implement Y?" | Source-by-source analysis with code, tradeoffs, applicability | +| **research-technical** (haiku, green) | Context7 | Official docs, API signatures, TypeScript types, configs, migration guides, "What's the official API?" | Exact API specs with types, configurations, official examples | + +## Agent Selection Decision Tree + +| Question Type | Agent Combination | Rationale | +|--------------|-------------------|-----------| +| **New technology/framework** | breadth + technical | Industry patterns + Official API | +| **Specific error/bug** | depth + technical | Detailed solutions + API reference | +| **API integration** | technical + depth | Official docs + Real examples | +| **Best practices/patterns** | breadth + depth | Industry trends + Case studies | +| **Comparison/decision** | breadth + depth | Broad survey + Detailed experiences | +| **Official API only** | technical | Just need documentation | + +**Default when unsure**: breadth + technical + +## Parallel Invocation Syntax + +**Always use Promise.all for parallel execution:** + +```typescript +await Promise.all([ + Task({ + subagent_type: 'research-breadth', // or 'research-depth' or 'research-technical' + model: 'haiku', + description: 'Brief description', + prompt: `Specific research question with focus areas and MCP tool guidance` + }), + + Task({ + subagent_type: 'research-technical', + model: 'haiku', + description: 'Brief description', + prompt: `Specific research question with focus areas and MCP tool guidance` + }) +]); +``` + +## Common Patterns + +### Pattern 1: New Technology +**Scenario**: Learning a new framework +**Agents**: breadth + technical +**Focus**: breadth (architectural patterns, industry trends), technical (official API, configs) +**Consolidation**: Industry patterns β†’ Official implementation + +### Pattern 2: Specific Solution +**Scenario**: Debugging or implementing known solution +**Agents**: depth + technical +**Focus**: depth (blog posts, implementations, gotchas), technical (official API, types) +**Consolidation**: Real-world patterns β†’ Official API usage + +### Pattern 3: API Integration +**Scenario**: Integrating with library/API +**Agents**: technical + depth +**Focus**: technical (official API, error codes), depth (tutorials, testing approaches) +**Consolidation**: Official API first β†’ Battle-tested patterns + +### Pattern 4: Comparative Analysis +**Scenario**: Choosing between approaches +**Agents**: breadth + depth +**Focus**: breadth (comparisons, trends), depth (migration experiences, lessons) +**Consolidation**: Industry trends β†’ Real experiences + +## Synthesis Strategy + +Use **research-synthesis skill** to consolidate findings: + +1. **Consolidate**: Group by theme, identify consensus, note contradictions +2. **Narrativize**: Weave findings into story (not bullet dumps): "Industry uses X (breadth), implemented via Y (technical), as shown by Z (depth)" +3. **Attribute**: Link claims to sources, note which agent provided insights +4. **Identify Gaps**: Unanswered questions, contradictions, disagreements +5. **Extract Actions**: Implementation path, code/configs, risks, constraints + +## Anti-Patterns vs Best Practices + +| ❌ Anti-Pattern | βœ… Best Practice | +|----------------|------------------| +| Single agent for multi-faceted question | 2-3 agents for comprehensive coverage | +| Sequential: `await` each agent | Parallel: `Promise.all([...])` | +| Copy agent outputs verbatim in sections | Synthesize into narrative with attribution | +| Skip source attribution | Note which agent/source for each claim | +| List findings separately | Weave into coherent story | + +## Complete Example + +**User**: "How do I implement real-time notifications in Next.js?" + +**Step 1: Analyze** β†’ New technology + implementation +**Step 2: Launch** β†’ breadth + technical in parallel +**Step 3: Synthesize**: + +```markdown +## Findings + +Industry research shows three approaches: SSE (most popular for Next.js), WebSockets +(bidirectional), Polling (fallback). Official Next.js docs indicate route handlers +support SSE via ReadableStream, but WebSockets require external service on Vercel. + +**Recommendation**: Use SSE via Next.js route handlers - aligns with framework +capabilities and industry best practices. + +**Implementation**: Create API route with ReadableStream β†’ Client uses EventSource +β†’ Handle reconnection/errors β†’ Consider Vercel limitations + +**Sources**: [Perplexity] Next.js real-time patterns 2024-2025 | [Context7] Next.js Route Handlers +``` + +## Integration Points + +**Used by**: +- `/research` command (essentials) - User-initiated research +- `implementing-tasks` skill (experimental) - Auto-launch when STUCK +- `planning` skill (experimental) - Uses exploration agents instead + +**Other agent categories**: +- **Exploration** (codebase): architecture-explorer + codebase-analyzer (parallel) +- **Review** (code quality): test-coverage + error-handling + security (all 3 parallel) diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md new file mode 100644 index 0000000..436a0f0 --- /dev/null +++ b/skills/technical-planning/SKILL.md @@ -0,0 +1,249 @@ +--- +name: technical-planning +description: Plans technical projects with risk-first development, milestone structuring, and managed deferral. Use when planning software projects, defining milestones, structuring development phases, or breaking down complex tasks into manageable iterations. +--- + +# Technical Planning + +## Core Principles + +**Focus on "What" Not "How"**: Define deliverable outcomes, not implementation details. Specify constraints and success criteria, but leave implementation choices flexible. + +**Last Responsible Moment**: Defer decisions until you have enough information to make them well, but not so late that they block progress. Make reversible decisions quickly; delay irreversible ones until necessary. + +**Risk-First Development**: Address highest-risk technical challenges first. Build proof-of-concepts before full implementation. Ship working but imperfect solutions to validate core assumptions early. + +**Managed Deferral**: Explicitly document what's being deferred and when it will be addressed. Distinguish between core value delivery and polish/optimization. + +### Progress Tracking with TodoWrite + +Use TodoWrite to track planning progress through the four phases: + +1. **At start**: Create todos for each phase: + ``` + ☐ Phase 1: Requirements & Risk Analysis + ☐ Phase 2: Milestone Planning + ☐ Phase 3: Implementation Strategy + ☐ Phase 4: Execution Framework + ``` + +2. **During planning**: Mark phases in_progress β†’ completed as you work through them. Add sub-todos for key deliverables: + ``` + ☐ Extract core requirements (2-3 user journeys) + ☐ Identify technical risks (high/integration/performance/architecture) + ☐ Define milestones with success criteria + ☐ Document deferred items with rationale + ``` + +3. **For complex projects**: Track clarifying questions and their resolutions as todos - prevents proceeding with incomplete information + +### Decision Timing Framework + +**Decide Early (Requirements Phase)**: +- User problems being solved +- Success criteria and measurement +- Hard constraints (security, compliance, performance SLAs) +- Critical integrations and dependencies +- Technology choices that affect architecture + +**Defer to Implementation (Execution Phase)**: +- Specific algorithms or data structures +- Internal API design details +- Code organization patterns +- Library choices (when multiple options work) +- Performance optimizations (until proven necessary) +- UI/UX details (until user testing) + +**Why**: Early decisions should enable work without locking in details. Implementation decisions become clearer with hands-on experience and often reveal better alternatives than upfront planning suggests. + +## Agent Guidelines + +**Seek Clarity Before Proceeding**: Never assume unclear requirements, technical constraints, or business priorities. Only proceed when you have 80%+ confidence on critical aspects. Ask specific questions about: + +- User problems being solved (not just features requested) +- Success criteria and measurement approaches +- Technical constraints and existing system dependencies +- Team capabilities and technology preferences +- Timeline constraints and priority trade-offs +- Performance and scalability requirements + +## Phase 1: Requirements & Risk Analysis + +### Prerequisites Check + +Verify: + +- What user problems are being solved? +- Who are the primary users and their workflows? +- How will success be measured? +- What are the technical and business constraints? + +### Extract Core Requirements + +1. Identify fundamental user problems being solved +2. Map primary user journeys (focus on 2-3 critical paths) +3. Define project success metrics + +### Identify Technical Risks + +1. **High-Impact Risks**: Technical unknowns that could invalidate the approach +2. **Integration Risks**: External system dependencies and compatibility concerns +3. **Performance Risks**: Scalability bottlenecks and algorithmic challenges +4. **Architecture Risks**: Fundamental design decisions with broad implications + +### Risk Prioritization Matrix + +- **Critical + Unknown**: Must be addressed in Milestone 1 with proof-of-concepts +- **Critical + Known**: Address in early milestones with established patterns +- **Non-Critical**: Defer to later milestones or eliminate + +## Phase 2: Milestone Planning + +### Prerequisites Check + +Verify: + +- Priority order of technical risks identified in Phase 1 +- Team capacity and available timeline +- Dependencies between different components +- Definition of "working functionality" for this project + +### Milestone Structure + +- **Timeline**: 4-8 week cycles based on project complexity +- **Deliverable**: Each milestone must produce working, testable functionality +- **Risk Focus**: Sequence milestones to tackle highest-risk items first + +### For Each Milestone, Define: + +**Goal**: One-sentence description of milestone outcome + +**Core Tasks**: 4-6 main implementation tasks following Last Responsible Moment principle: +- Define clear outcomes and constraints +- Identify dependencies and integration points +- Provide context and considerations (not step-by-step instructions) +- Leave implementation details flexible +- Flag questions to resolve during execution + +**Success Criteria**: +- Minimum Viable Success (must achieve for milestone completion) +- Complete Success (ideal outcome including polish) + +**Risk Mitigation**: Specific unknowns to be resolved in this milestone + +**Deferred Items**: What's intentionally left out and target milestone for inclusion + +### Task Breakdown Guidelines + +When breaking down tasks, provide **guidance not prescription**: + +**βœ“ Good Task Definition** (outcome-focused): +- Goal: "Enable users to authenticate securely" +- Constraints: "Must integrate with existing session middleware; <100ms response time" +- Guidance: "Consider session vs. token auth; review existing patterns in src/middleware/" +- Validation: "Users can log in, sessions persist, tests pass" + +**βœ— Poor Task Definition** (overly prescriptive): +- Step 1: "Create file auth.js with bcrypt import" +- Step 2: "Write hashPassword function using bcrypt.hash with 10 rounds" +- Step 3: "Create Express middleware checking req.session.userId" + +**Why**: Good definitions let the implementer choose the best approach based on what they learn. Poor definitions lock in choices before understanding the context, often leading to rework. + +### Example Milestone Definition + +**Goal**: Validate user authentication and basic data retrieval from external API + +**Core Tasks**: +1. Implement OAuth flow with provider +2. Create user session management +3. Build API client with error handling +4. Add basic user profile display + +**Success Criteria**: +- Minimum: Users can log in and see their profile data +- Complete: Include profile editing and session persistence + +**Risk Mitigation**: Confirm API rate limits and response time under load + +**Deferred**: Advanced profile features, password reset flow (Milestone 3) + +## Phase 3: Implementation Strategy + +### Development Approach + +- **Prototype First**: Build throwaway versions to test risky assumptions +- **Core Before Polish**: Implement functional features before UI refinements +- **Integration Early**: Test external system connections in first milestone +- **Measure Continuously**: Track performance and user metrics from day one + +### Technology Selection Criteria + +1. **Team Expertise**: Prefer technologies your team knows well +2. **Proven Reliability**: Choose mature, battle-tested options for core systems +3. **Integration Capability**: Ensure compatibility with existing tools/systems +4. **Scalability Path**: Technology should support anticipated growth + +### Quality Gates + +- All code must have basic test coverage +- Performance benchmarks must be met for core user journeys +- Security review required for authentication and data handling +- Accessibility standards met for user-facing features + +## Phase 4: Execution Framework + +### Sprint Planning + +1. **Risk Assessment**: Identify unknowns in upcoming work +2. **Exploration Time**: Reserve 20-30% of sprint for prototyping/learning +3. **Definition of Done**: Must include working functionality, not just completed code +4. **Continuous Validation**: Regular stakeholder feedback on core user journeys + +### Deferral Management + +- **Regular Review**: Evaluate deferred items each milestone for continued relevance +- **Categories**: Technical debt, UX polish, edge cases, performance optimization, advanced features +- **Scheduling**: Plan deferred items into appropriate future milestones +- **Elimination**: Some deferred items may become unnecessary + +### Documentation Requirements + +- Technical specification focusing on deliverable outcomes +- Risk register with mitigation plans +- Deferred items registry with target scheduling +- Architecture decision records for major choices + +## Decision Framework for Agents + +**IF** project has unknown technical feasibility β†’ Schedule proof-of-concept in Milestone 1 +**IF** project requires external integrations β†’ Test minimal integration in first milestone +**IF** project has performance requirements β†’ Establish benchmarks and test core algorithms early +**IF** team lacks expertise in chosen technology β†’ Include learning/exploration time in early milestones +**IF** project has tight deadlines β†’ Focus on minimum viable success criteria and defer polish +**IF** project is greenfield β†’ Spend extra time on architecture decisions and foundational setup +**IF** project is enhancement β†’ Focus on integration points and backward compatibility + +### When Unclear - Ask These Questions + +**WHEN** requirements are vague β†’ "What specific user problem does this solve? How will we measure success?" +**WHEN** technical scope is undefined β†’ "What are the must-have vs. nice-to-have technical capabilities?" +**WHEN** timeline is unrealistic β†’ "What are the non-negotiable deadlines and what flexibility exists?" +**WHEN** team capabilities are unknown β†’ "What technologies does the team have experience with? What are the skill gaps?" +**WHEN** integration points are unclear β†’ "What existing systems must this connect to? What are the data formats and API constraints?" +**WHEN** performance needs are unspecified β†’ "What are the expected user loads and response time requirements?" +**WHEN** success criteria are missing β†’ "How will we know this milestone is complete and successful?" + +## Common Pitfalls to Avoid + +- **Making assumptions instead of asking clarifying questions** when requirements are unclear +- **Proceeding with incomplete information** rather than requesting necessary details +- **Creating overly prescriptive task definitions** with step-by-step instructions instead of outcome-focused guidance +- **Making implementation decisions too early** when they could be deferred to execution +- Spending time on low-risk features while deferring critical unknowns +- Over-engineering solutions before validating core assumptions +- Planning implementation details instead of focusing on deliverable outcomes +- **Guessing at user needs** instead of understanding specific problems being solved +- Failing to document deferral decisions and rationale +- Optimizing prematurely instead of proving core functionality first +- **Locking in technology choices** before understanding the full context diff --git a/skills/writing-documentation/SKILL.md b/skills/writing-documentation/SKILL.md new file mode 100644 index 0000000..7750865 --- /dev/null +++ b/skills/writing-documentation/SKILL.md @@ -0,0 +1,191 @@ +--- +name: writing-documentation +description: Produces concise, clear documentation by applying Elements of Style principles. Use when writing or improving any technical documentation (READMEs, guides, API docs, architecture docs). Not for code comments. +--- + +# Writing Documentation Skill + +Apply Strunk & White's *Elements of Style* principles to produce concise, clear technical documentation. + +## When to Use This Skill + +**Use this skill when:** +- Writing new documentation (README, API docs, guides, tutorials, architecture docs) +- Improving existing documentation +- Reviewing documentation for quality +- User asks to "make this more concise" or "improve clarity" +- User mentions: documentation, docs, README, guide, tutorial, API docs + +**Do NOT use this skill for:** +- Code comments (different context, separate skill needed) +- Marketing copy (requires persuasive voice, not neutral clarity) +- Personal blog posts (requires individual voice) + +## Workflows + +### Workflow 1: Write New Documentation + +**Steps:** + +1. **Understand the purpose** + - [ ] What is the primary goal of this documentation? + - [ ] Who is the target audience? + - [ ] What do readers need to accomplish after reading? + +2. **Load writing principles** + - [ ] Read `reference/strunk-white-principles.md` to internalize core principles + +3. **Determine documentation type** + - [ ] Read `reference/doc-types.md` to select appropriate type + - [ ] Identify essential sections based on guidelines + +4. **Draft the documentation** + - [ ] Apply Strunk & White principles while writing + +5. **Validate quality** + - [ ] Run through Quality Checklist (below) + - [ ] Verify all essential information is present + - [ ] Confirm document achieves its purpose + +### Workflow 2: Improve Existing Documentation + +**Steps:** + +1. **Read the current documentation** + - [ ] Understand its purpose and audience + - [ ] Note specific problems (verbosity, unclear sections, missing info) + +2. **Load writing principles** + - [ ] Read `reference/strunk-white-principles.md` + - [ ] Review `reference/examples.md` for before/after patterns + +3. **Apply improvements** + - [ ] Remove needless words + - [ ] Convert passive to active voice + - [ ] Strengthen vague statements + - [ ] Eliminate redundancy + - [ ] Improve organization if needed + +4. **Validate improvements** + - [ ] Run through Quality Checklist + - [ ] Verify no information was lost + - [ ] Confirm clarity improved + +### Workflow 3: Review Documentation + +**Steps:** + +1. **Load writing principles** + - [ ] Read `reference/strunk-white-principles.md` + - [ ] Review relevant guidelines in `reference/doc-types.md` + +2. **Assess against quality criteria** + - [ ] Run through Quality Checklist (below) + - [ ] Note specific violations with examples + +3. **Provide feedback** + - [ ] List specific issues found + - [ ] Reference violated principles + - [ ] Suggest concrete improvements + +## Decision Framework + +### When to Write vs Improve + +**Write new documentation when:** +- No documentation exists +- Existing documentation is fundamentally wrong or outdated +- Complete restructuring needed (cheaper to rewrite) + +**Improve existing documentation when:** +- Core structure and information are sound +- Style or clarity issues can be fixed incrementally +- Specific sections need enhancement + +### Choosing Documentation Type + +See `reference/doc-types.md` for detailed guidelines. Quick reference: + +- **README**: Project overview, quick start, primary entry point +- **API Documentation**: Reference for function/endpoint signatures and behavior +- **Tutorial/Guide**: Step-by-step learning path for accomplishing specific goals +- **Architecture/Design Doc**: Explain system structure, decisions, and tradeoffs +- **CLI Tool Documentation**: Command reference with options and examples + +### Prioritizing Conciseness vs Comprehensiveness + +**Prioritize conciseness when:** +- Documentation type is reference (README, API docs, CLI docs) +- Readers need to scan quickly +- Getting started / quick start sections + +**Prioritize comprehensiveness when:** +- Documentation type is learning-focused (tutorials, guides) +- Complex concepts require detailed explanation +- Architecture decisions need thorough justification + +**Balance both:** +- Use concise overview sections with detailed subsections +- Link to comprehensive resources rather than embedding everything +- Apply progressive disclosure pattern + +## Quality Checklist + +### Content +- [ ] Purpose is clear +- [ ] Essential information is present +- [ ] No unnecessary information +- [ ] Correct and accurate + +### Writing (Core Principles) +- [ ] Active voice predominates +- [ ] Definite statements (not hedging) +- [ ] Positive form +- [ ] Specific, concrete language +- [ ] Concise (no needless words) + +### Structure +- [ ] Logical organization +- [ ] Clear headings +- [ ] Scannable +- [ ] Examples where helpful + +### Technical Documentation +- [ ] Code examples are executable +- [ ] Commands include full context +- [ ] Prerequisites are stated +- [ ] Error cases are covered + +## Reference Files + +### When to Load Each Reference + +**Load `reference/strunk-white-principles.md`:** +- At the start of EVERY documentation writing/improvement task +- When reviewing documentation + +**Load `reference/doc-types.md`:** +- When choosing what type of documentation to write +- When unsure about essential sections for a doc type +- When reviewing documentation structure + +**Load `reference/examples.md`:** +- When improving existing documentation (see patterns) +- When you want concrete before/after examples + +## Common Pitfalls + +**Skipping Principle Loading**: ALWAYS load `reference/strunk-white-principles.md` before writing. + +**Following Guidelines Rigidly**: Adapt to the specific project's needs. Some projects don't need all sections; some need additional ones. + +**Over-Editing**: "Omit needless words" means remove words that add no value. Keep all information that serves the reader's purpose. + +**Sacrificing Accuracy for Brevity**: Accuracy always wins. Express explanations concisely, but never misleadingly. + +**Inconsistent Terminology**: Choose one term for each concept and use it consistently. + +## Notes + +- This skill works iteratively - you can run it multiple times on the same document without degrading quality (idempotent) +- Quality over quantity - a short, clear document is better than a comprehensive, confusing one diff --git a/skills/writing-documentation/reference/doc-types.md b/skills/writing-documentation/reference/doc-types.md new file mode 100644 index 0000000..dc53d42 --- /dev/null +++ b/skills/writing-documentation/reference/doc-types.md @@ -0,0 +1,354 @@ +# Documentation Type Guidelines + +Guidelines for different types of technical documentation. Use these principles to determine what to write and how to structure it based on your project's needs. + +## Decision Framework + +### Choosing Documentation Type + +**What is the reader's primary goal?** +- Quick start / understand what this is β†’ **README** +- Look up API/function signature β†’ **API Reference** +- Learn how to accomplish a task β†’ **Tutorial / Guide** +- Understand system design β†’ **Architecture Documentation** +- Use a command-line tool β†’ **CLI Documentation** + +**What is the reader's experience level?** +- Newcomer to the project β†’ README, Tutorial +- Experienced with the project β†’ API Reference, Architecture +- Operator/deployer β†’ Operations Guide + +**What is the reader's context?** +- Evaluating whether to use this β†’ README +- Already using, needs details β†’ API Reference, Guide +- Debugging or troubleshooting β†’ API Reference, Troubleshooting Guide +- Extending or modifying β†’ Architecture Documentation + +### Combining Documentation Types + +**Minimal project** (small library): +- README (with inline API reference if simple) + +**Standard project** (library or tool): +- README (overview, quick start) +- API Reference (detailed documentation) +- Guide (common usage patterns) + +**Large project** (framework or platform): +- README (overview, links to other docs) +- Getting Started Tutorial +- API Reference (comprehensive) +- Multiple topic-specific Guides +- Architecture Documentation +- Contributing Guide +- Operations Guide + +--- + +## README + +### Purpose +Primary entry point answering: What is this? Why should I care? How do I get started? + +### Target Audience +Developers evaluating whether to use your project and getting started for the first time. + +### Typical Sections + +**Title and Description** (required): +- Project name +- One-sentence description +- Who it's for (if not obvious) + +**Installation** (required): +- Primary installation method +- Prerequisites (language version, system requirements) +- Verification step + +**Quick Start** (required): +- Minimal working example +- Expected output +- Link to full documentation + +**Features** (if not obvious from description): +- 3-7 main capabilities +- Distinguishing characteristics +- Key use cases + +**Documentation Links** (if docs exist elsewhere): +- Getting Started Guide +- API Reference +- Advanced Usage + +**License** (required for open source): +- License type +- Link to full license text + +**Optional sections** (include only if they add clear value): +- Badges (build status, version, coverage) +- Contributing (how to report issues, submit changes) +- Prerequisites (if complex setup required) +- Configuration (if essential and complex) +- FAQ (if common questions exist) + +### Key Guidelines + +- Keep under 300 lines (preferably under 200) +- Focus on getting started quickly +- Link to detailed docs rather than embedding everything +- Use working, tested code examples +- Update as the project evolves + +--- + +## API Reference Documentation + +### Purpose +Comprehensive reference for developers using your library or API. Answers: What functions/endpoints are available? What parameters do they accept? What do they return? + +### Target Audience +Developers already using your API who need to look up specific details. + +### Document for Each API Element + +**Signature**: +- Function/method/endpoint name +- Parameters with types +- Return type +- HTTP method and path (for REST APIs) + +**Description**: +- One-sentence summary +- Additional context if needed (keep brief) + +**Parameters**: +- Name, type, required/optional +- Description +- Default value (if optional) +- Constraints or valid values + +**Return Value**: +- Type +- Description +- Structure (if complex) + +**Errors/Exceptions**: +- Exception types thrown +- Conditions that trigger each +- HTTP status codes (for REST APIs) + +**Example**: +- Minimal working example +- Common usage patterns +- Error handling (if relevant) + +### Organization + +**For libraries**: +- Group by module or category +- Alphabetical within groups (or by importance) +- Consistent format for each entry + +**For REST APIs**: +- Group by resource +- List endpoints per resource +- Show request and response examples + +### Key Guidelines + +- Document every public function/endpoint +- Specify types precisely +- Include executable examples +- Document all error conditions +- Keep descriptions concise + +--- + +## Tutorials and Guides + +### Purpose +Teach readers how to accomplish specific tasks or learn concepts. + +### Difference: Tutorial vs Guide + +**Tutorial**: +- Step-by-step learning path +- Builds one thing from start to finish +- Assumes minimal knowledge + +**Guide**: +- Explains a concept or pattern +- May skip basic steps +- Assumes familiarity with basics + +### Typical Structure + +**Introduction**: +- What you'll build/learn +- Why it's useful +- Estimated time (for tutorials) +- Prerequisites + +**Setup**: +- Required software and versions +- Initial project setup +- Dependencies to install + +**Step-by-Step Instructions**: +- What to do +- Why you're doing it (context) +- Code to add +- Expected result +- Verification/testing at each step + +**Conclusion**: +- Summary of what was built/learned +- Suggestions for extending or improving +- Links to related documentation + +### Key Guidelines + +- Build incrementally with verification at each step +- Explain reasoning behind decisions +- Provide working, tested code +- Include troubleshooting for common issues +- Test end-to-end before publishing + +--- + +## Architecture Documentation + +### Purpose +Explain how the system is designed and why. Answers: How is the system structured? Why did we make these design decisions? What are the tradeoffs? + +### Target Audience +Developers contributing to the project, teams evaluating the system, future maintainers. + +### Typical Sections + +**Overview**: +- What the system does +- Major components +- How components interact + +**Component Details**: +- Responsibility of each component +- Key interfaces +- Dependencies +- Technology choices + +**Design Decisions**: +- What decision was made +- Why it was made +- What alternatives were considered +- What tradeoffs were accepted + +**Data Flow**: +- How data moves through the system +- Request/response flows +- Data transformations + +**Deployment** (if relevant): +- Infrastructure components +- Scaling characteristics +- Failure modes and recovery + +### Key Guidelines + +- Focus on high-level structure and key decisions +- Explain tradeoffs and alternatives +- Use diagrams for complex flows +- Update as the system evolves + +--- + +## CLI Tool Documentation + +### Purpose +Help users operate command-line tools. Answers: What commands are available? What do they do? What options do they accept? + +### Target Audience +Users running your command-line tool. + +### Typical Sections + +**Installation**: +- Installation command +- Prerequisites +- Verification step + +**Basic Usage**: +- Simplest useful command +- Common patterns +- Help command + +**Commands** (for each command): +- Command name and signature +- Description +- Arguments (name, description) +- Options/flags (name, description, default) +- Examples (2-3 common use cases) + +**Configuration** (if applicable): +- Config file location and format +- Available options +- Precedence (env vars, config file, flags) + +**Exit Codes** (for scripting): +- Exit code meanings +- When each code is returned + +### Key Guidelines + +- Show complete, working commands +- Include common use cases +- Document all options and flags +- Keep help text concise but complete + +--- + +## Common Patterns Across All Types + +### Progressive Disclosure +- Start with essentials +- Link to detailed information +- Don't embed everything in one document + +### Examples First +- Show working example early +- Then explain details +- Examples should be executable + +### Consistent Structure +- Use same format for similar elements +- Maintain parallel construction +- Keep terminology consistent + +### Scannable Format +- Clear headings +- Bullet points for lists +- Code blocks for commands/examples +- Tables for structured data + +### Link Between Docs +- README β†’ Getting Started β†’ Guides β†’ API Reference +- Cross-reference related documentation +- Keep each doc focused on its purpose + +--- + +## Anti-Patterns + +**Don't**: +- Mix documentation types (e.g., tutorials in API reference) +- Duplicate content across multiple docs +- Include implementation details in user-facing docs +- Assume knowledge not stated in prerequisites +- Let documentation drift from reality + +**Do**: +- Keep each doc type focused on its purpose +- Link to canonical information rather than duplicating +- Focus on interface, not implementation +- State all prerequisites explicitly +- Update docs when code changes diff --git a/skills/writing-documentation/reference/examples.md b/skills/writing-documentation/reference/examples.md new file mode 100644 index 0000000..7b4dde7 --- /dev/null +++ b/skills/writing-documentation/reference/examples.md @@ -0,0 +1,311 @@ +# Documentation Examples: Before and After + +Concrete examples of documentation improvements by applying Strunk & White principles. Each example includes annotations explaining key changes. + +## Example 1: README - Project Description + +### Before (73 words) + +``` +# MyProject + +This is basically a really awesome library that we've built in order to help developers +who are working with data processing tasks. It's something that you might want to +consider using if you happen to be dealing with situations where you need to validate, +transform, or otherwise manipulate data in your applications. We think it's pretty useful +and it has been designed in such a way that it's fairly easy to use. +``` + +### After (17 words) + +``` +# MyProject + +A TypeScript library for validating and transforming structured data. + +Supports JSON, XML, and CSV formats with built-in validation rules. +``` + +### Key Changes + +**Removed needless words**: +- "basically", "really awesome", "we've built", "in order to help" +- "you might want to consider using if you happen to be" +- "pretty useful", "fairly easy", "in such a way that" + +**Removed hedging and qualifiers**: +- "basically", "pretty", "fairly", "might", "happen to be" + +**Used definite, specific language**: +- "A TypeScript library" instead of vague description +- "Supports JSON, XML, and CSV" instead of "various different types" +- Listed capabilities directly instead of hedging + +**Result**: 77% shorter while conveying all essential information. + +--- + +## Example 2: API Documentation - Function Description + +### Before (119 words) + +``` +### validateData() + +This function is used for the purpose of validating data that has been provided by the user. +It should be noted that the function will perform various checks on the input data in order +to ensure that it meets the requirements that have been specified in the schema. In the +event that the validation process fails, an error will be returned to the calling code. + +You might want to consider using this function whenever you need to make sure that user +input is valid before you process it further. + +Parameters: +- data: This is the data that you want to validate +- schema: This represents the validation rules + +Returns: A result object will be returned that contains information about whether the +validation succeeded or failed. +``` + +### After (38 words + example) + +**Function signature:** +``` +validateData(data, schema, options) +``` + +**Description:** +Validates data against a schema and returns the result. + +**Parameters:** +- `data` (any): Data to validate +- `schema` (Schema): Validation rules +- `options` (ValidationOptions, optional): Configuration + +**Returns:** +- `ValidationResult`: { valid: boolean, errors: array } + +**Example:** +```javascript +const result = validateData( + { email: 'user@example.com' }, + { email: 'email' } +); +``` + +### Key Changes + +**Removed weak constructions**: +- "is used for the purpose of" β†’ "Validates" +- "It should be noted that" β†’ removed +- "in order to ensure" β†’ implicit in "validates" +- "in the event that" β†’ shown in example +- "will be returned" β†’ "Returns" + +**Removed hedging**: +- "You might want to consider" β†’ removed (focus on what it does) +- "various checks" β†’ removed vague description + +**Added specificity**: +- Type information for all parameters +- Exact return structure +- Working code example + +**Result**: More information in fewer words, scannable format. + +--- + +## Example 3: Tutorial - Installation Section + +### Before (139 words) + +``` +## Getting Started with Installation + +Before you can actually start using MyProject, you're going to need to install it first. +The installation process is actually pretty straightforward and shouldn't take too long. + +First of all, you need to make sure that you have Node.js installed on your system. If +you don't already have Node.js, you should probably go ahead and install it. You'll want +to use a relatively recent version - we'd recommend using something like version 14 or +higher, but newer versions should work fine too. + +Once you've got Node.js set up and ready to go, you can then proceed to install MyProject +itself. Just open up your terminal and type in the following command: + +npm install myproject + +After npm finishes downloading and installing all of the necessary dependencies, you +should be all set! +``` + +### After (28 words) + +**Section heading:** +``` +## Installation +``` + +**Content:** + +Requires Node.js 14 or later. + +Install via npm: +```bash +npm install myproject +``` + +Verify installation: +```javascript +const myproject = require('myproject'); +console.log(myproject.version); +``` + +### Key Changes + +**Eliminated filler**: +- "Before you can actually start using", "pretty straightforward", "shouldn't take too long" +- "First of all", "Once you've got", "all set and ready" +- All explanatory preamble removed + +**Removed hedging**: +- "you're going to need to", "you should probably" +- "we'd recommend something like", "should work fine too" +- "Just open up your terminal and type in" + +**Made actionable**: +- Direct commands instead of instructions about commands +- Added verification step (concrete action) +- Removed obvious explanations (why you need Node.js) + +**Result**: 80% shorter, faster to execute. + +--- + +## Example 4: Architecture Documentation - Design Decision + +### Before (172 words) + +``` +## Why We Decided to Use Message Queues + +After quite a bit of discussion and consideration of various different options, we made +the decision to use message queues (specifically RabbitMQ) for communication between our +different services. This was something that we thought about pretty carefully because it's +an important architectural decision. + +Basically, the main reason why we went with message queues is because they help to decouple +the services from each other. What this means is that if one service happens to go down or +become unavailable for whatever reason, it won't necessarily cause problems for the other +services. The messages will just queue up and wait. + +Another thing that's nice about using message queues is that they make it easier to handle +situations where you might have sudden spikes in traffic. The queue can act as a sort of +buffer. + +We did consider some alternative approaches. One option we looked at was just having the +services call each other directly using HTTP APIs, which would have been simpler in some +ways. But we ultimately felt that the benefits outweighed the added complexity. +``` + +### After (72 words) + +**Section heading:** +``` +## Design Decision: Message Queue Communication +``` + +**Decision**: Use RabbitMQ message queues for inter-service communication. + +**Rationale**: + +Services remain operational when dependencies fail. If the Processing Service crashes, +the Ingest Service continues accepting requests. Processing resumes when the service recovers. + +Message queues buffer traffic spikes without overwhelming downstream services. + +**Alternatives Considered**: + +Direct HTTP calls: +- Simpler infrastructure (no message broker) +- Tight coupling - failures cascade +- No built-in buffering + +**Tradeoffs**: + +Added operational complexity (RabbitMQ cluster to maintain) and eventual consistency +(messages process asynchronously) for improved resilience. + +### Key Changes + +**Removed qualifiers and hedging**: +- "quite a bit of discussion", "various different options", "something that we thought about pretty carefully" +- "basically", "what this means is", "might have", "sort of" +- All process description removed + +**Used active voice and structure**: +- "we made the decision" β†’ "Decision:" header +- Organized into clear sections: Decision, Rationale, Alternatives, Tradeoffs +- Parallel construction throughout + +**Made statements specific**: +- "help to decouple the services" β†’ concrete example of decoupling +- "easier to handle situations where you might have sudden spikes" β†’ "buffer traffic spikes" +- "simpler in some ways" β†’ specific simplicity (infrastructure) +- "benefits outweighed the added complexity" β†’ explicit tradeoffs listed + +**Result**: 58% shorter, scannable structure, clear decision record. + +--- + +## Common Patterns Across Examples + +### Pattern 1: Remove Hedging +- Before: "You might want to consider possibly using..." +- After: "Use..." + +### Pattern 2: Use Active Voice +- Before: "An error will be returned by the function..." +- After: "The function returns an error..." + +### Pattern 3: Be Specific +- Before: "Use a recent version of Node.js" +- After: "Use Node.js 14 or later" + +### Pattern 4: Remove Needless Words +- Before: "In order to install the package..." +- After: "To install the package..." +- Better: "Install via npm:" + +### Pattern 5: Lead with Action +- Before: "If you want to process a file, you would run..." +- After: "Process a file:\n```\ncommand file\n```" + +### Pattern 6: Show, Don't Tell +- Before: "The function is easy to use" +- After: [Show a simple example] + +--- + +## Applying These Patterns + +**First pass - Remove needless words**: +- Search for "in order to", "for the purpose of", "due to the fact that" +- Eliminate "basically", "actually", "really", "just", "simply" +- Remove qualifiers: "quite", "very", "rather", "somewhat" + +**Second pass - Strengthen voice**: +- Convert passive to active +- Replace weak verbs (is, has, can be) with strong verbs +- Remove "there is/are" constructions + +**Third pass - Increase specificity**: +- Replace vague terms with specific values +- Replace "various", "several", "some" with actual items +- Add concrete examples + +**Fourth pass - Structure**: +- Use parallel construction in lists +- Lead with action +- Break long paragraphs into focused sections diff --git a/skills/writing-documentation/reference/strunk-white-principles.md b/skills/writing-documentation/reference/strunk-white-principles.md new file mode 100644 index 0000000..6808c5f --- /dev/null +++ b/skills/writing-documentation/reference/strunk-white-principles.md @@ -0,0 +1,674 @@ +# Elements of Style - Principles for Technical Documentation + +Core writing principles from Strunk & White's *Elements of Style*, adapted for technical documentation. Load this file before writing or improving any documentation. + +## Summary: The 10 Core Principles + +1. **Use active voice** - "The function returns X" not "X is returned" +2. **Put statements in positive form** - "Do X" not "Don't avoid X" +3. **Use definite, specific, concrete language** - Numbers, versions, exact behavior +4. **Omit needless words** - Every word must tell +5. **Express coordinate ideas in similar form** - Parallel construction +6. **Keep related words together** - Subject near verb, verb near object +7. **Choose a suitable design and hold to it** - Consistent structure +8. **Make the paragraph the unit of composition** - One topic per paragraph +9. **Avoid a succession of loose sentences** - Vary sentence structure +10. **Place emphatic words at the end** - End strong, not with qualifications + +## Table of Contents + +### I. Elementary Principles of Composition +- [Use the Active Voice](#use-the-active-voice) +- [Put Statements in Positive Form](#put-statements-in-positive-form) +- [Use Definite, Specific, Concrete Language](#use-definite-specific-concrete-language) +- [Omit Needless Words](#omit-needless-words) +- [Express Coordinate Ideas in Similar Form](#express-coordinate-ideas-in-similar-form) +- [Keep Related Words Together](#keep-related-words-together) +- [Choose a Suitable Design and Hold to It](#choose-a-suitable-design-and-hold-to-it) +- [Make the Paragraph the Unit of Composition](#make-the-paragraph-the-unit-of-composition) +- [Avoid a Succession of Loose Sentences](#avoid-a-succession-of-loose-sentences) +- [Place Emphatic Words at the End](#place-emphatic-words-at-the-end) + +### II. Approach to Style +- [Place Yourself in the Background](#place-yourself-in-the-background) +- [Write in a Way That Comes Naturally](#write-in-a-way-that-comes-naturally) +- [Work from a Suitable Design](#work-from-a-suitable-design) +- [Write with Nouns and Verbs](#write-with-nouns-and-verbs) +- [Revise and Rewrite](#revise-and-rewrite) +- [Do Not Overwrite](#do-not-overwrite) +- [Do Not Overstate](#do-not-overstate) +- [Avoid Fancy Words](#avoid-fancy-words) +- [Be Clear](#be-clear) +- [Do Not Inject Opinion](#do-not-inject-opinion) +- [Use Figures of Speech Sparingly](#use-figures-of-speech-sparingly) +- [Avoid Foreign Languages](#avoid-foreign-languages) +- [Prefer the Standard to the Offbeat](#prefer-the-standard-to-the-offbeat) + +### III. Common Patterns in Technical Writing +- [Weak Constructions to Replace](#weak-constructions-to-replace) +- [Common Qualifiers to Avoid](#common-qualifiers-to-avoid) +- [Passive Voice Patterns](#passive-voice-patterns) +- [Vague Technical Phrases](#vague-technical-phrases) + +### IV. Technical Documentation Specifics +- [Code Examples](#code-examples) +- [Command Documentation](#command-documentation) +- [API Documentation](#api-documentation) +- [Error Messages](#error-messages) + +--- + +## I. Elementary Principles of Composition + +### Use the Active Voice + +Active voice is direct and vigorous. Passive voice is indirect and weak. + +**Pattern**: Subject performs action (active) vs subject receives action (passive) + +**Bad** (passive): +``` +The file is opened by the function. +An error will be returned if validation fails. +``` + +**Good** (active): +``` +The function opens the file. +The function returns an error if validation fails. +``` + +**Acceptable passive** (when actor is unknown or irrelevant): +``` +The data is encrypted before transmission. +The file was created in 2023. +``` + +--- + +### Put Statements in Positive Form + +Make definite assertions. Avoid tame, hesitating language. + +**Bad** (negative/hesitant): +``` +Do not forget to set the API key. +You might want to consider using the --verbose flag. +It's not uncommon for users to encounter this error. +``` + +**Good** (positive/definite): +``` +Set the API key before making requests. +Use the --verbose flag for detailed output. +Users commonly encounter this error. +``` + +--- + +### Use Definite, Specific, Concrete Language + +Prefer the specific to the general, the definite to the vague, the concrete to the abstract. + +**Bad** (vague): +``` +The function runs pretty fast. +Use a recent version of Node.js. +It supports various databases. +``` + +**Good** (specific): +``` +The function processes 10,000 records per second. +Use Node.js 18.0 or later. +It supports PostgreSQL 12+, MySQL 8+, and SQLite 3.35+. +``` + +--- + +### Omit Needless Words + +Vigorous writing is concise. Every word should tell. + +**Common needless phrases**: + +| Wordy | Concise | +|-------|---------| +| in order to | to | +| for the purpose of | for | +| due to the fact that | because | +| at this point in time | now | +| has the ability to | can | +| make a determination | determine | +| give consideration to | consider | +| in the event that | if | +| there is/are | [restructure] | +| it is [adjective] that | [restructure] | + +**Bad**: +``` +In order to install the package, you will need to run the following command. +It should be noted that this function has the ability to process large files. +``` + +**Good**: +``` +To install the package, run this command. +This function can process large files. +``` + +**Remove these qualifiers**: very, really, quite, rather, somewhat, fairly, pretty, basically, essentially, actually, just, simply, merely + +--- + +### Express Coordinate Ideas in Similar Form + +Parallel construction makes related ideas easier to recognize. + +**Bad** (not parallel): +``` +The library provides: +- Data validation +- Transforming data +- To sanitize inputs +``` + +**Good** (parallel): +``` +The library provides: +- Data validation +- Data transformation +- Input sanitization +``` + +--- + +### Keep Related Words Together + +Words that form a unit should not be separated. Keep subject near verb, verb near object. + +**Bad** (separated): +``` +The function, when called with invalid input, returns an error. +The user must, before sending any requests, configure the API key. +``` + +**Good** (together): +``` +The function returns an error when called with invalid input. +The user must configure the API key before sending requests. +``` + +--- + +### Choose a Suitable Design and Hold to It + +A document's organization should match its purpose. Maintain structure consistently. + +**For technical documentation**: +- READMEs: Overview β†’ Installation β†’ Usage β†’ Configuration +- API docs: Endpoints grouped by resource, consistent format +- Tutorials: Sequential steps, each building on previous +- Architecture docs: Context β†’ Decision β†’ Consequences + +--- + +### Make the Paragraph the Unit of Composition + +Each paragraph addresses a single topic. Begin with a topic sentence. + +**Bad** (multiple topics): +``` +This function processes user input. It also validates the data and stores it in the database. +Error handling is important because invalid data can cause crashes. +``` + +**Good** (one topic per paragraph): +``` +This function processes user input and returns a boolean indicating success. + +The function validates input before processing. Invalid data returns false immediately. + +On successful validation, the function stores the data in the database. +``` + +--- + +### Avoid a Succession of Loose Sentences + +Vary sentence structure. Mix short and long sentences. Use subordination to show relationships. + +**Bad** (all loose): +``` +Create a file. Name it config.json. Open it. Add content. Save it. Run the app. +``` + +**Good** (varied): +``` +Create a file named config.json and add the following content. When you run the +application, it reads this config file and applies your settings. +``` + +--- + +### Place Emphatic Words at the End + +The end of a sentence is the most emphatic position. + +**Bad** (weak endings): +``` +Run the tests before deploying, if possible. +Configure the database connection string first, typically. +``` + +**Good** (emphatic endings): +``` +Before deploying, run the tests. +First, configure the database connection string. +``` + +--- + +## II. Approach to Style + +### Place Yourself in the Background + +Write in a way that draws attention to the subject matter, not the writer. + +**Bad** (writer-focused): +``` +I think you should use the --verbose flag. +We believe this is the right solution. +``` + +**Good** (subject-focused): +``` +Use the --verbose flag for detailed output. +This solution addresses the core requirements. +``` + +--- + +### Write in a Way That Comes Naturally + +Avoid forced or artificial language. + +**Bad** (forced): +``` +One must ensure that the configuration file is properly instantiated prior to +executing the application binary. +``` + +**Good** (natural): +``` +Create and configure the config file before running the application. +``` + +--- + +### Work from a Suitable Design + +Plan the structure before writing. Outline major sections to ensure logical flow. + +--- + +### Write with Nouns and Verbs + +Strong nouns and verbs carry meaning. Minimize adjectives and adverbs. + +**Bad** (weak): +``` +The function does validation of the input very quickly. +``` + +**Good** (strong): +``` +The function validates the input in 10ms. +``` + +--- + +### Revise and Rewrite + +First drafts are rarely optimal. Edit ruthlessly. + +**Editing checklist**: +- Remove needless words +- Convert passive to active voice +- Replace vague words with specific ones +- Eliminate qualifiers +- Verify examples are executable + +--- + +### Do Not Overwrite + +Don't use ten words when five will do. + +**Bad**: +``` +First and foremost, it is absolutely essential to validate user input before processing. +``` + +**Good**: +``` +Validate user input before processing. +``` + +--- + +### Do Not Overstate + +Avoid hyperbole and exaggeration. + +**Bad**: +``` +This revolutionary approach completely solves all performance problems. +``` + +**Good**: +``` +This approach reduces response time by 40%. +``` + +--- + +### Avoid Fancy Words + +Use simple, direct language. + +| Fancy | Simple | +|-------|--------| +| utilize | use | +| implement | use, add, create | +| leverage | use | +| facilitate | help, enable | +| commence | begin, start | +| terminate | end, stop | + +--- + +### Be Clear + +Clarity is the primary goal. Sacrifice everything else for clarity. + +**Unclear**: +``` +The function may return null if the parameter is invalid or the operation fails +depending on the configuration. +``` + +**Clear**: +``` +The function returns null in two cases: +- The parameter is invalid +- The operation fails and config.failSafe is true +``` + +--- + +### Do Not Inject Opinion + +State facts, not judgments. + +**Bad** (opinion): +``` +The old API was terrible and poorly designed. +``` + +**Good** (fact): +``` +The old API required three requests to accomplish this task. The new API requires one. +``` + +--- + +### Use Figures of Speech Sparingly + +Metaphors can clarify, but technical accuracy matters more. + +**Appropriate**: +``` +The service acts as a gatekeeper, allowing only authenticated requests. +``` + +**Unnecessary**: +``` +The function dances through the data, gracefully extracting information. +``` + +--- + +### Avoid Foreign Languages + +Use English terms when they exist. + +**Appropriate** (established terms): +``` +ad hoc query +de facto standard +``` + +**Inappropriate**: +``` +Use the library vis-Γ -vis data processing. +``` + +--- + +### Prefer the Standard to the Offbeat + +Use conventional language and structure. Avoid clever or quirky language. + +--- + +## III. Common Patterns in Technical Writing + +### Weak Constructions to Replace + +**"There is/are"**: +- Bad: There are three methods available. +- Good: Three methods are available. +- Better: Use any of three methods. + +**"It is"**: +- Bad: It is important to note that validation is required. +- Good: Validation is required. + +**"In order to"**: +- Bad: In order to install, run npm install. +- Good: To install, run npm install. + +**"Has the ability to"**: +- Bad: The function has the ability to process large files. +- Good: The function processes large files. + +--- + +### Common Qualifiers to Avoid + +Eliminate or justify each instance: + +very, really, quite, rather, somewhat, fairly, pretty (as in "pretty fast"), relatively, comparatively, possibly, probably, perhaps, maybe, might, arguably, seemingly, apparently, generally, usually (unless specifying frequency), typically, basically, essentially, actually, just, simply, merely + +**Bad**: +``` +This is a fairly simple process. +Just run this command. +``` + +**Good**: +``` +This is a simple process. +Run this command. +``` + +--- + +### Passive Voice Patterns + +Recognize and replace: + +**"Is/are/was/were [verb]ed by"**: +- Bad: The file is opened by the function. +- Good: The function opens the file. + +**"Should be [verb]ed"**: +- Bad: The API key should be configured before use. +- Good: Configure the API key before use. + +**"Will be [verb]ed"**: +- Bad: An error will be returned if validation fails. +- Good: The function returns an error if validation fails. + +--- + +### Vague Technical Phrases + +Replace with specific information: + +**"Various", "several"**: +- Bad: Supports various databases. +- Good: Supports PostgreSQL, MySQL, and SQLite. + +**"Some", "certain"**: +- Bad: Some configurations require additional setup. +- Good: Configurations with authentication require additional setup. + +**"May", "might"** (when certainty exists): +- Bad: This may cause errors. +- Good: This causes 'Invalid Input' errors. + +**"Appropriate", "proper"** (without defining): +- Bad: Configure the settings appropriately. +- Good: Set timeout to 30 seconds and max_retries to 3. + +**"Recent", "latest"** (without version): +- Bad: Use a recent version of Node.js. +- Good: Use Node.js 18.0 or later. + +**"Fast", "slow"** (without measurement): +- Bad: The function is fast. +- Good: The function processes 10,000 records per second. + +--- + +## IV. Technical Documentation Specifics + +### Code Examples + +**Principles**: +- All code examples must be executable +- Show complete, working code +- Include necessary imports and setup +- Specify language for syntax highlighting + +**Bad** (incomplete): +``` +user = authenticate(username, password) +``` + +**Good** (complete): +```javascript +const { authenticate } = require('./auth'); + +const user = await authenticate(username, password); +if (user) { + console.log('Authentication successful'); +} +``` + +--- + +### Command Documentation + +**Principles**: +- Show complete commands with all flags +- Include working directory context when relevant +- Show expected output + +**Bad**: +``` +Run the tests. +``` + +**Good**: +```bash +# Run all tests +npm test + +# Run specific test file +npm test -- auth.test.js +``` + +--- + +### API Documentation + +**Document for each function/endpoint**: +- Signature with types +- Description (one sentence + context if needed) +- Parameters (name, type, required/optional, description) +- Return value (type, description) +- Errors/exceptions +- Example usage + +**Example**: +``` +validate(schema: Schema, data: unknown): ValidationResult + +Validates data against a schema. + +Parameters: +- schema (Schema, required): Validation rules +- data (unknown, required): Data to validate + +Returns: +- ValidationResult: { valid: boolean, errors: ValidationError[] } + +Throws: +- SchemaError: If schema is invalid + +Example: +const result = validate(schema, { email: 'user@example.com' }); +``` + +--- + +### Error Messages + +**Document common errors**: +- Show actual error message +- Explain cause +- Provide concrete solution + +**Example**: +``` +Error: "ECONNREFUSED" +Cause: Cannot connect to database. +Solution: Verify database is running: systemctl status postgresql +``` + +--- + +## Quick Reference: Editing Passes + +**First pass - Remove needless words**: +- Search for "in order to", "for the purpose of", "due to the fact that" +- Eliminate qualifiers: "quite", "very", "rather", "somewhat" +- Remove "basically", "actually", "really", "just", "simply" + +**Second pass - Strengthen voice**: +- Convert passive to active +- Remove "there is/are" constructions +- Replace weak verbs (is, has, can be) with strong verbs + +**Third pass - Increase specificity**: +- Replace vague terms with specific values +- Replace "various", "several" with actual items +- Add concrete examples + +**Fourth pass - Structure**: +- Use parallel construction in lists +- Break long paragraphs into focused sections +- Place emphatic words at the end