ai-qakit 1.0.0

package/templates/.claude/skills/command-development/references/documentation-patterns.md

@@ -0,0 +1,739 @@
+# Command Documentation Patterns
+
+Strategies for creating self-documenting, maintainable commands with excellent user experience.
+
+## Overview
+
+Well-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.
+
+## Self-Documenting Command Structure
+
+### Complete Command Template
+
+```markdown
+---
+description: Clear, actionable description under 60 chars
+argument-hint: [arg1] [arg2] [optional-arg]
+allowed-tools: Read, Bash(git:*)
+model: sonnet
+---
+
+<!--
+COMMAND: command-name
+VERSION: 1.0.0
+AUTHOR: Team Name
+LAST UPDATED: 2025-01-15
+
+PURPOSE:
+Detailed explanation of what this command does and why it exists.
+
+USAGE:
+  /command-name arg1 arg2
+
+ARGUMENTS:
+  arg1: Description of first argument (required)
+  arg2: Description of second argument (optional, defaults to X)
+
+EXAMPLES:
+  /command-name feature-branch main
+    → Compares feature-branch with main
+
+  /command-name my-branch
+    → Compares my-branch with current branch
+
+REQUIREMENTS:
+  - Git repository
+  - Branch must exist
+  - Permissions to read repository
+
+RELATED COMMANDS:
+  /other-command - Related functionality
+  /another-command - Alternative approach
+
+TROUBLESHOOTING:
+  - If branch not found: Check branch name spelling
+  - If permission denied: Check repository access
+
+CHANGELOG:
+  v1.0.0 (2025-01-15): Initial release
+  v0.9.0 (2025-01-10): Beta version
+-->
+
+# Command Implementation
+
+[Command prompt content here...]
+
+[Explain what will happen...]
+
+[Guide user through steps...]
+
+[Provide clear output...]
+```
+
+### Documentation Comment Sections
+
+**PURPOSE**: Why the command exists
+- Problem it solves
+- Use cases
+- When to use vs when not to use
+
+**USAGE**: Basic syntax
+- Command invocation pattern
+- Required vs optional arguments
+- Default values
+
+**ARGUMENTS**: Detailed argument documentation
+- Each argument described
+- Type information
+- Valid values/ranges
+- Defaults
+
+**EXAMPLES**: Concrete usage examples
+- Common use cases
+- Edge cases
+- Expected outputs
+
+**REQUIREMENTS**: Prerequisites
+- Dependencies
+- Permissions
+- Environmental setup
+
+**RELATED COMMANDS**: Connections
+- Similar commands
+- Complementary commands
+- Alternative approaches
+
+**TROUBLESHOOTING**: Common issues
+- Known problems
+- Solutions
+- Workarounds
+
+**CHANGELOG**: Version history
+- What changed when
+- Breaking changes highlighted
+- Migration guidance
+
+## In-Line Documentation Patterns
+
+### Commented Sections
+
+```markdown
+---
+description: Complex multi-step command
+---
+
+<!-- SECTION 1: VALIDATION -->
+<!-- This section checks prerequisites before proceeding -->
+
+Checking prerequisites...
+- Git repository: !`git rev-parse --git-dir 2>/dev/null`
+- Branch exists: [validation logic]
+
+<!-- SECTION 2: ANALYSIS -->
+<!-- Analyzes the differences between branches -->
+
+Analyzing differences between $1 and $2...
+[Analysis logic...]
+
+<!-- SECTION 3: RECOMMENDATIONS -->
+<!-- Provides actionable recommendations -->
+
+Based on analysis, recommend:
+[Recommendations...]
+
+<!-- END: Next steps for user -->
+```
+
+### Inline Explanations
+
+```markdown
+---
+description: Deployment command with inline docs
+---
+
+# Deploy to $1
+
+## Pre-flight Checks
+
+<!-- We check branch status to prevent deploying from wrong branch -->
+Current branch: !`git branch --show-current`
+
+<!-- Production deploys must come from main/master -->
+if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then
+  ⚠️  WARNING: Not on main branch for production deploy
+  This is unusual. Confirm this is intentional.
+fi
+
+<!-- Test status ensures we don't deploy broken code -->
+Running tests: !`npm test`
+
+✓ All checks passed
+
+## Deployment
+
+<!-- Actual deployment happens here -->
+<!-- Uses blue-green strategy for zero-downtime -->
+Deploying to $1 environment...
+[Deployment steps...]
+
+<!-- Post-deployment verification -->
+Verifying deployment health...
+[Health checks...]
+
+Deployment complete!
+
+## Next Steps
+
+<!-- Guide user on what to do after deployment -->
+1. Monitor logs: /logs $1
+2. Run smoke tests: /smoke-test $1
+3. Notify team: /notify-deployment $1
+```
+
+### Decision Point Documentation
+
+```markdown
+---
+description: Interactive deployment command
+---
+
+# Interactive Deployment
+
+## Configuration Review
+
+Target: $1
+Current version: !`cat version.txt`
+New version: $2
+
+<!-- DECISION POINT: User confirms configuration -->
+<!-- This pause allows user to verify everything is correct -->
+<!-- We can't automatically proceed because deployment is risky -->
+
+Review the above configuration.
+
+**Continue with deployment?**
+- Reply "yes" to proceed
+- Reply "no" to cancel
+- Reply "edit" to modify configuration
+
+[Await user input before continuing...]
+
+<!-- After user confirms, we proceed with deployment -->
+<!-- All subsequent steps are automated -->
+
+Proceeding with deployment...
+```
+
+## Help Text Patterns
+
+### Built-in Help Command
+
+Create a help subcommand for complex commands:
+
+```markdown
+---
+description: Main command with help
+argument-hint: [subcommand] [args]
+---
+
+# Command Processor
+
+if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
+  **Command Help**
+
+  USAGE:
+    /command [subcommand] [args]
+
+  SUBCOMMANDS:
+    init [name]       Initialize new configuration
+    deploy [env]      Deploy to environment
+    status            Show current status
+    rollback          Rollback last deployment
+    help              Show this help
+
+  EXAMPLES:
+    /command init my-project
+    /command deploy staging
+    /command status
+    /command rollback
+
+  For detailed help on a subcommand:
+    /command [subcommand] --help
+
+  Exit.
+fi
+
+[Regular command processing...]
+```
+
+### Contextual Help
+
+Provide help based on context:
+
+```markdown
+---
+description: Context-aware command
+argument-hint: [operation] [target]
+---
+
+# Context-Aware Operation
+
+if [ -z "$1" ]; then
+  **No operation specified**
+
+  Available operations:
+  - analyze: Analyze target for issues
+  - fix: Apply automatic fixes
+  - report: Generate detailed report
+
+  Usage: /command [operation] [target]
+
+  Examples:
+    /command analyze src/
+    /command fix src/app.js
+    /command report
+
+  Run /command help for more details.
+
+  Exit.
+fi
+
+[Command continues if operation provided...]
+```
+
+## Error Message Documentation
+
+### Helpful Error Messages
+
+```markdown
+---
+description: Command with good error messages
+---
+
+# Validation Command
+
+if [ -z "$1" ]; then
+  ❌ ERROR: Missing required argument
+
+  The 'file-path' argument is required.
+
+  USAGE:
+    /validate [file-path]
+
+  EXAMPLE:
+    /validate src/app.js
+
+  Try again with a file path.
+
+  Exit.
+fi
+
+if [ ! -f "$1" ]; then
+  ❌ ERROR: File not found: $1
+
+  The specified file does not exist or is not accessible.
+
+  COMMON CAUSES:
+  1. Typo in file path
+  2. File was deleted or moved
+  3. Insufficient permissions
+
+  SUGGESTIONS:
+  - Check spelling: $1
+  - Verify file exists: ls -la $(dirname "$1")
+  - Check permissions: ls -l "$1"
+
+  Exit.
+fi
+
+[Command continues if validation passes...]
+```
+
+### Error Recovery Guidance
+
+```markdown
+---
+description: Command with recovery guidance
+---
+
+# Operation Command
+
+Running operation...
+
+!`risky-operation.sh`
+
+if [ $? -ne 0 ]; then
+  ❌ OPERATION FAILED
+
+  The operation encountered an error and could not complete.
+
+  WHAT HAPPENED:
+  The risky-operation.sh script returned a non-zero exit code.
+
+  WHAT THIS MEANS:
+  - Changes may be partially applied
+  - System may be in inconsistent state
+  - Manual intervention may be needed
+
+  RECOVERY STEPS:
+  1. Check operation logs: cat /tmp/operation.log
+  2. Verify system state: /check-state
+  3. If needed, rollback: /rollback-operation
+  4. Fix underlying issue
+  5. Retry operation: /retry-operation
+
+  NEED HELP?
+  - Check troubleshooting guide: /help troubleshooting
+  - Contact support with error code: ERR_OP_FAILED_001
+
+  Exit.
+fi
+```
+
+## Usage Example Documentation
+
+### Embedded Examples
+
+```markdown
+---
+description: Command with embedded examples
+---
+
+# Feature Command
+
+This command performs feature analysis with multiple options.
+
+## Basic Usage
+
+\`\`\`
+/feature analyze src/
+\`\`\`
+
+Analyzes all files in src/ directory for feature usage.
+
+## Advanced Usage
+
+\`\`\`
+/feature analyze src/ --detailed
+\`\`\`
+
+Provides detailed analysis including:
+- Feature breakdown by file
+- Usage patterns
+- Optimization suggestions
+
+## Use Cases
+
+**Use Case 1: Quick overview**
+\`\`\`
+/feature analyze .
+\`\`\`
+Get high-level feature summary of entire project.
+
+**Use Case 2: Specific directory**
+\`\`\`
+/feature analyze src/components
+\`\`\`
+Focus analysis on components directory only.
+
+**Use Case 3: Comparison**
+\`\`\`
+/feature analyze src/ --compare baseline.json
+\`\`\`
+Compare current features against baseline.
+
+---
+
+Now processing your request...
+
+[Command implementation...]
+```
+
+### Example-Driven Documentation
+
+```markdown
+---
+description: Example-heavy command
+---
+
+# Transformation Command
+
+## What This Does
+
+Transforms data from one format to another.
+
+## Examples First
+
+### Example 1: JSON to YAML
+**Input:** `data.json`
+\`\`\`json
+{"name": "test", "value": 42}
+\`\`\`
+
+**Command:** `/transform data.json yaml`
+
+**Output:** `data.yaml`
+\`\`\`yaml
+name: test
+value: 42
+\`\`\`
+
+### Example 2: CSV to JSON
+**Input:** `data.csv`
+\`\`\`csv
+name,value
+test,42
+\`\`\`
+
+**Command:** `/transform data.csv json`
+
+**Output:** `data.json`
+\`\`\`json
+[{"name": "test", "value": "42"}]
+\`\`\`
+
+### Example 3: With Options
+**Command:** `/transform data.json yaml --pretty --sort-keys`
+
+**Result:** Formatted YAML with sorted keys
+
+---
+
+## Your Transformation
+
+File: $1
+Format: $2
+
+[Perform transformation...]
+```
+
+## Maintenance Documentation
+
+### Version and Changelog
+
+```markdown
+<!--
+VERSION: 2.1.0
+LAST UPDATED: 2025-01-15
+AUTHOR: DevOps Team
+
+CHANGELOG:
+  v2.1.0 (2025-01-15):
+    - Added support for YAML configuration
+    - Improved error messages
+    - Fixed bug with special characters in arguments
+
+  v2.0.0 (2025-01-01):
+    - BREAKING: Changed argument order
+    - BREAKING: Removed deprecated --old-flag
+    - Added new validation checks
+    - Migration guide: /migration-v2
+
+  v1.5.0 (2024-12-15):
+    - Added --verbose flag
+    - Improved performance by 50%
+
+  v1.0.0 (2024-12-01):
+    - Initial stable release
+
+MIGRATION NOTES:
+  From v1.x to v2.0:
+    Old: /command arg1 arg2 --old-flag
+    New: /command arg2 arg1
+
+  The --old-flag is removed. Use --new-flag instead.
+
+DEPRECATION WARNINGS:
+  - The --legacy-mode flag is deprecated as of v2.1.0
+  - Will be removed in v3.0.0 (estimated 2025-06-01)
+  - Use --modern-mode instead
+
+KNOWN ISSUES:
+  - #123: Slow performance with large files (workaround: use --stream flag)
+  - #456: Special characters in Windows (fix planned for v2.2.0)
+-->
+```
+
+### Maintenance Notes
+
+```markdown
+<!--
+MAINTENANCE NOTES:
+
+CODE STRUCTURE:
+  - Lines 1-50: Argument parsing and validation
+  - Lines 51-100: Main processing logic
+  - Lines 101-150: Output formatting
+  - Lines 151-200: Error handling
+
+DEPENDENCIES:
+  - Requires git 2.x or later
+  - Uses jq for JSON processing
+  - Needs bash 4.0+ for associative arrays
+
+PERFORMANCE:
+  - Fast path for small inputs (< 1MB)
+  - Streams large files to avoid memory issues
+  - Caches results in /tmp for 1 hour
+
+SECURITY CONSIDERATIONS:
+  - Validates all inputs to prevent injection
+  - Uses allowed-tools to limit Bash access
+  - No credentials in command file
+
+TESTING:
+  - Unit tests: tests/command-test.sh
+  - Integration tests: tests/integration/
+  - Manual test checklist: tests/manual-checklist.md
+
+FUTURE IMPROVEMENTS:
+  - TODO: Add support for TOML format
+  - TODO: Implement parallel processing
+  - TODO: Add progress bar for large files
+
+RELATED FILES:
+  - lib/parser.sh: Shared parsing logic
+  - lib/formatter.sh: Output formatting
+  - config/defaults.yml: Default configuration
+-->
+```
+
+## README Documentation
+
+Commands should have companion README files:
+
+```markdown
+# Command Name
+
+Brief description of what the command does.
+
+## Installation
+
+This command is part of the [plugin-name] plugin.
+
+Install with:
+\`\`\`
+/plugin install plugin-name
+\`\`\`
+
+## Usage
+
+Basic usage:
+\`\`\`
+/command-name [arg1] [arg2]
+\`\`\`
+
+## Arguments
+
+- `arg1`: Description (required)
+- `arg2`: Description (optional, defaults to X)
+
+## Examples
+
+### Example 1: Basic Usage
+\`\`\`
+/command-name value1 value2
+\`\`\`
+
+Description of what happens.
+
+### Example 2: Advanced Usage
+\`\`\`
+/command-name value1 --option
+\`\`\`
+
+Description of advanced feature.
+
+## Configuration
+
+Optional configuration file: `.claude/command-name.local.md`
+
+\`\`\`markdown
+---
+default_arg: value
+enable_feature: true
+---
+\`\`\`
+
+## Requirements
+
+- Git 2.x or later
+- jq (for JSON processing)
+- Node.js 14+ (optional, for advanced features)
+
+## Troubleshooting
+
+### Issue: Command not found
+
+**Solution:** Ensure plugin is installed and enabled.
+
+### Issue: Permission denied
+
+**Solution:** Check file permissions and allowed-tools setting.
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - See [LICENSE](LICENSE).
+
+## Support
+
+- Issues: https://github.com/user/plugin/issues
+- Docs: https://docs.example.com
+- Email: support@example.com
+```
+
+## Best Practices
+
+### Documentation Principles
+
+1. **Write for your future self**: Assume you'll forget details
+2. **Examples before explanations**: Show, then tell
+3. **Progressive disclosure**: Basic info first, details available
+4. **Keep it current**: Update docs when code changes
+5. **Test your docs**: Verify examples actually work
+
+### Documentation Locations
+
+1. **In command file**: Core usage, examples, inline explanations
+2. **README**: Installation, configuration, troubleshooting
+3. **Separate docs**: Detailed guides, tutorials, API reference
+4. **Comments**: Implementation details for maintainers
+
+### Documentation Style
+
+1. **Clear and concise**: No unnecessary words
+2. **Active voice**: "Run the command" not "The command can be run"
+3. **Consistent terminology**: Use same terms throughout
+4. **Formatted well**: Use headings, lists, code blocks
+5. **Accessible**: Assume reader is beginner
+
+### Documentation Maintenance
+
+1. **Version everything**: Track what changed when
+2. **Deprecate gracefully**: Warn before removing features
+3. **Migration guides**: Help users upgrade
+4. **Archive old docs**: Keep old versions accessible
+5. **Review regularly**: Ensure docs match reality
+
+## Documentation Checklist
+
+Before releasing a command:
+
+- [ ] Description in frontmatter is clear
+- [ ] argument-hint documents all arguments
+- [ ] Usage examples in comments
+- [ ] Common use cases shown
+- [ ] Error messages are helpful
+- [ ] Requirements documented
+- [ ] Related commands listed
+- [ ] Changelog maintained
+- [ ] Version number updated
+- [ ] README created/updated
+- [ ] Examples actually work
+- [ ] Troubleshooting section complete
+
+With good documentation, commands become self-service, reducing support burden and improving user experience.