Initial commit

skills/prompt-writing/references/examples/command-examples.md

@@ -0,0 +1,66 @@
+## Command Examples
+
+**Good Command with $ARGUMENTS:**
+
+```
+Analyze GitHub issue $ARGUMENTS and implement a fix:
+
+1. Run `gh issue view $ARGUMENTS` to read the issue
+2. Identify the root cause
+3. Write tests that reproduce the bug
+4. Implement the fix
+5. Verify tests pass
+6. Comment on the issue with your solution
+```
+
+Why it works: Flexible with any issue number, treats all input as one string.
+Usage: /fix-issue 123
+
+**Good Command with Positional Parameters:**
+
+```
+Review PR #$1 with priority $2 and assign to $3.
+
+Focus on:
+- Security vulnerabilities
+- Performance implications
+- Code style consistency
+
+Report findings and tag $3 for follow-up.
+```
+
+Why it works: Accesses each argument individually for different purposes.
+Usage: /review-pr 456 high alice
+
+**When to use each:**
+
+$ARGUMENTS: When you want all input as a single value (issue numbers, commit messages, search queries)
+
+$1, $2, $3: When you need to handle multiple distinct pieces of information (PR number + priority + assignee, or feature name + test type + output format)
+
+**Bad Command:**
+
+```
+Fix the bug.
+```
+
+Why it's bad: No process, no context, too vague.
+
+**Good Command:**
+
+```
+Implement the feature using test-driven development:
+
+1. Read the feature description from work-items.md
+2. Write a failing test that verifies the feature
+3. Run the test to confirm it fails
+4. Write minimal code to make the test pass
+5. Run tests to verify they pass
+6. Run full test suite to check for regressions
+7. Update scratchpad with progress
+
+If stuck after 3 attempts, log the blocker and ask for guidance.
+```
+
+Why it works: Clear steps, explicit process, handles failure.
+

skills/prompt-writing/references/examples/document-examples.md

@@ -0,0 +1,66 @@
+## Document Examples
+
+**Good Documentation Prompt:**
+
+```
+Document the authentication system for our Rails API. Include:
+
+1. Overview: How authentication works in our system
+2. Setup: How to configure authentication for a new service
+3. Usage: How to authenticate requests (with code examples)
+4. Token management: How tokens are created, refreshed, and revoked
+5. Security considerations: Best practices and common pitfalls
+
+Write in clear prose with code examples. Assume the reader is a developer familiar with Rails but new to our codebase.
+```
+
+Why it works: Clear scope, specific sections, target audience defined.
+
+**Bad Documentation Prompt:**
+
+```
+Write docs about the auth system.
+```
+
+Why it's bad: No scope, no structure, no audience.
+
+## Reference Document Examples
+
+**Good Reference (using plain paths):**
+
+```
+# Project Context
+
+This is a Rails subscription management app.
+
+## Architecture
+- Authentication: app/services/auth/
+- Payments: app/services/payments/ using Stripe
+- Background jobs: app/jobs/ using Sidekiq
+
+## Conventions
+- Use RSpec with AAA pattern
+- Services are single-purpose classes
+- API uses JSON:API format
+
+## Troubleshooting
+For authentication errors, see docs/auth-troubleshooting.md
+For payment issues, see docs/payment-debugging.md
+```
+
+Why it works: Concise essentials, points to detailed docs with plain paths.
+
+**Bad Reference (forcing imports when not necessary):**
+
+```
+# Project Context
+
+@docs/architecture.md
+@docs/conventions.md
+@docs/troubleshooting.md
+@docs/payment-guide.md
+@docs/testing-guide.md
+```
+
+Why it's bad: Forces all content into context immediately, bloats context window.
+

skills/prompt-writing/references/examples/skill-examples.md

@@ -0,0 +1,38 @@
+## Skill Examples
+
+**Good Skill Structure:**
+
+```
+---
+name: testing-guide
+description: Guidance on writing effective tests using RSpec and TDD practices
+---
+
+# Testing Guide
+
+This skill provides testing guidance for Rails applications using RSpec.
+
+## Quick Reference
+- Use descriptive test names
+- Follow AAA pattern (Arrange, Act, Assert)
+- Mock external dependencies
+- Test behavior, not implementation
+
+<aaa_pattern>
+## Arrange-Act-Assert Pattern
+
+Structure tests in three clear phases:
+- Arrange: Set up test data and conditions
+- Act: Execute the code being tested
+- Assert: Verify the results
+
+Example: [concrete example here]
+</aaa_pattern>
+
+<mocking>
+[Detailed guidance on mocking...]
+</mocking>
+```
+
+Why it works: Overview first, progressive disclosure for details.
+

skills/prompt-writing/references/examples/subagent-examples.md

@@ -0,0 +1,51 @@
+## Subagent Examples
+
+**Good Subagent:**
+
+```
+---
+name: test-runner
+description: Use PROACTIVELY after code changes to run tests and fix failures. Analyzes test output and provides fixes.
+tools: Read, Bash, Grep
+model: inherit
+---
+
+You are a test runner specialist. When invoked:
+
+1. Run the appropriate test suite for changed files
+2. If tests pass, report success
+3. If tests fail:
+   - Analyze the failure output
+   - Identify the root cause
+   - Propose a fix
+   - Implement the fix if within your capability
+   - Re-run tests to verify
+
+Constraints:
+- Never skip tests
+- Always run full suite after fixes
+- If stuck after 3 attempts, report the blocker clearly
+
+Output Format:
+- Test results summary
+- Failures with root cause
+- Fixes applied
+- Final status
+```
+
+Why it works: Clear trigger in description, specific workflow, appropriate tools, handles failure.
+
+**Bad Subagent:**
+
+```
+---
+name: helper
+description: Helps with stuff
+---
+
+You help with coding tasks.
+```
+
+Why it's bad: Vague description (no trigger conditions), vague purpose, no workflow.
+
+</examples>

skills/prompt-writing/references/examples/technique-examples.md

@@ -0,0 +1,79 @@
+<examples>
+
+## Chain-of-Thought Examples
+
+**Good CoT Prompt:**
+"A train travels 120 miles in 2 hours, then 180 miles in 3 hours. What is its average speed for the entire journey? Think through this step by step, showing your calculations."
+
+Why it works: Complex calculation benefits from showing intermediate steps.
+
+**Bad CoT Prompt:**
+"What is 5 + 3? Think step by step."
+
+Why it's bad: Trivial calculation doesn't benefit from step-by-step reasoning.
+
+## Few-Shot Examples
+
+**Good Few-Shot Prompt:**
+
+```
+Convert user stories into test descriptions:
+
+Example 1:
+User Story: As a user, I want to reset my password so I can regain access
+Test: User can request password reset and receive email with reset link
+
+Example 2:
+User Story: As an admin, I want to deactivate accounts so I can manage access
+Test: Admin can deactivate user account and user loses access
+
+Now convert:
+User Story: As a user, I want to filter search results by date
+```
+
+Why it works: Format transformation isn't obvious, examples show the pattern.
+
+**Bad Few-Shot Prompt:**
+
+```
+Write Python functions.
+
+Example: def add(a, b): return a + b
+
+Now write a multiply function.
+```
+
+Why it's bad: Writing basic functions is standard knowledge, examples add no value.
+
+## XML Context Separation Examples
+
+**Good XML Usage:**
+
+```
+<codebase_context>
+Rails app using RSpec for testing, FactoryBot for test data, Pundit for authorization
+</codebase_context>
+
+<work_items>
+1. Add admin role
+2. Restrict user deletion to admins
+3. Add admin dashboard
+</work_items>
+
+<instructions>
+For each work item, follow TDD: write failing test, implement feature, verify tests pass
+</instructions>
+```
+
+Why it works: Three distinct information types clearly separated.
+
+**Bad XML Usage:**
+
+```
+<instructions>
+Write code that works and follows our standards.
+</instructions>
+```
+
+Why it's bad: Single vague piece of information doesn't need XML.
+