From claude-reliability
Guides creation of structured how-to documentation for reusable procedures, with templates for context, steps, troubleshooting, and CLI commands for managing guides.
npx claudepluginhub drmaciver/claude-reliability --plugin claude-reliabilityThis skill uses the workspace's default tool permissions.
Create a how-to when you:
Provides templates, structure, and principles for writing task-oriented How-To guides in documentation: actionable steps for users with specific goals like configuration or deployment.
Creates practical technical documentation like READMEs, runbooks, API references, setup guides, and troubleshooting notes, matching repo conventions and style.
Generates or updates documentation for code, APIs, or systems including READMEs, API references, inline comments, technical guides, and ADRs.
Share bugs, ideas, or general feedback.
Create a how-to when you:
Start with "How to..." and be specific:
Brief explanation of when to use this guide:
Use this guide when you need to release a new version to production.
Prerequisites: All tests passing, version bumped.
Numbered steps, each doing one thing:
1. Ensure all tests pass: `just test`
2. Bump the version in Cargo.toml
3. Create a git tag: `git tag v1.2.3`
4. Push with tags: `git push --tags`
5. Wait for CI to publish
Common problems and solutions:
## Troubleshooting
### CI fails on publish
- Check if version already exists on registry
- Verify credentials are not expired
claude-reliability howto create \
-t "How to add a new API endpoint" \
-i "... markdown content ..."
When a task needs to follow a procedure:
claude-reliability work link-howto <work-item-id> --howto-id <howto-id>
Now when viewing the task, the guidance is visible.
Find relevant guides:
claude-reliability howto search "deploy"
claude-reliability howto list # See all
claude-reliability howto update <id> -i "... new content ..."
claude-reliability howto delete <id>
# How to Add a New Database Migration
Use this guide when adding a new table or modifying the schema.
## Prerequisites
- Database access configured
- Migration tool installed
## Steps
1. Create a new migration file:
sqlx migrate add <migration_name>
2. Edit the generated file in `migrations/` with your SQL
3. Test locally:
sqlx migrate run
4. Verify the changes work:
cargo test
5. Commit the migration file
## Troubleshooting
### "migration failed: relation already exists"
The migration may have partially run. Check the database state and either:
- Drop the partial changes manually, or
- Adjust the migration to be idempotent (IF NOT EXISTS)
### "cannot find migration"
Ensure the migration file is in the correct directory and has the `.sql` extension.
When making architecture or design decisions, record the rationale alongside the decision. Without recorded rationale, future developers face a dilemma: blindly accept past decisions or blindly reverse them.
What to capture:
Format: Keep it lightweight — a short paragraph in a commit message, a comment block at the top of a module, or a dedicated decision record. The key is that the rationale is captured somewhere durable and discoverable.
ADRs are particularly valuable for decisions that seem arbitrary or surprising. If you chose a less obvious approach for a good reason, that reason must be written down or it will be lost.
When a non-obvious decision or constraint affects multiple locations in the codebase, write the detailed explanation once in a canonical location with a clear heading, and reference it elsewhere with a short comment.
Example:
// In the canonical location:
// Note [Why we validate before serializing]
// We must validate all fields before serializing because the serializer
// assumes well-formed input and will produce corrupt output otherwise.
// This was discovered in issue #42 when partial records caused silent
// data corruption.
// In other files that relate to this:
// See Note [Why we validate before serializing] in validator.rs
This prevents comment duplication and drift while keeping code well-documented. Write the explanation once, reference it everywhere.