magnus919_agent-skills/docs/runbooks.md

Runbooks

This document references incident response procedures for the agent-skills repository.

When Something Goes Wrong

CI Validation Failure

1. Check the GitHub Actions validate workflow
2. Review the failing step output for specific error messages
3. Common failures and resolutions:

Failure	Likely Cause	Resolution
ruff check fails	Code style violation	Run make format locally, then make lint
mypy fails	Type annotation error	Fix type annotations per mypy output
radon fails	Complexity threshold exceeded	Refactor complex function into smaller units
pytest fails	Test regression	Reproduce locally with make test
deptry fails	Unused or missing dependency	Run make deps and update requirements-dev.txt
validate-skills.rb fails	Invalid SKILL.md format	Check frontmatter YAML, relative links
eval-coverage ratchet fails	Schema-valid manifest coverage decreased	Add evals/evals.json to modified/new skills

Generated Artifact Staleness

If CI reports stale catalog artifacts:

ruby scripts/gen-claude-marketplace.rb --write
ruby scripts/gen-codex-plugin.rb --write
ruby scripts/gen-llms-txt.rb --write
git add .claude-plugin/ .codex-plugin/ llms.txt
git commit -m "chore: refresh generated artifacts"

Security Vulnerability in Dependency

1. Review the bandit or Dependabot alert
2. Update the affected dependency in requirements-dev.txt
3. Run make validate to confirm no regressions
4. Review the changelog of the updated dependency for breaking changes

Pre-commit Hook Issues

If pre-commit hooks are blocking commits:

# Run all hooks manually to see errors
pre-commit run --all-files

# Update hooks to latest versions
pre-commit autoupdate

Deployment

This repository has no deployment step. All changes are validated in CI and merged to main. Catalog artifacts (llms.txt, marketplace.json, plugin.json) are tracked in the repository and refreshed on each change.

Monitoring

Dashboards

• GitHub Actions dashboard — CI pipeline health and deploy status
• GitHub Actions validate workflow — Primary validation pipeline
• GitHub Security Advisories — Vulnerability alerts and advisory history
• Dependabot alerts — Dependency update PRs and security notifications

Deploy Impact Visibility

• All changes flow through the validate workflow on each push and PR
• CI status is visible in PR checks and on the Actions tab
• Release notes are auto-generated in CHANGELOG.md
• Release history is tracked in GitHub Releases
• CI failures on main automatically create tracking issues (via ci-failure-to-issue.yml workflow)