Skill: bug-management
You are managing defects using a strict, auditable bug log for process learning and metrics.
Canonical bug log (single source of truth)
All bugs/issues must be recorded in:
- •
docs/quality/BUG_LOG.md
If the file does not exist, create it using the required table format below.
When to log a bug
Log a bug entry whenever ANY of these occur:
- •A defect is discovered during implementation or local verification
- •QA report finds a defect (even if “minor”)
- •A user reports an issue in production or staging
- •A regression is introduced or suspected
- •A requirement/design inconsistency is found that would cause incorrect behavior if implemented
Who can be the detector
The “Detected by” field must be one of:
- •
agent:developer - •
agent:qa - •
agent:po - •
human:edgar - •
human:dev - •
user:prod - •
user:staging - •
system:monitoring
(Use the closest match; do not invent identities.)
Detection phase (where it was found)
Must be one of:
- •
requirement - •
analysis - •
design - •
implementation - •
testing - •
deployment - •
maintenance
Injection phase (where it likely originated)
For every bug, attempt to identify the most likely injection phase:
- •
requirement - •
analysis - •
design - •
implementation - •
testing - •
deployment - •
maintenance - •
unknown
Rules:
- •Prefer one injection phase. If uncertain, use
unknownand explain in notes. - •If the defect is a mismatch between docs and code, pick the phase that introduced the mismatch (usually design or implementation).
Required BUG_LOG.md table format
docs/quality/BUG_LOG.md MUST contain a markdown table with these columns (exact names):
| Bug ID | Title | Detected date | Detected phase | Detected by | Severity | Feature slug | Injected phase (suspected) | Root cause summary | Status | PR/Commit | Notes |
|---|
Field rules:
- •Bug ID:
BUG-0001incremental, never reused - •Severity:
S0(critical) /S1(high) /S2(medium) /S3(low) - •Status:
open/in-progress/blocked/fixed/won't-fix - •Feature slug: link to
docs/features/<slug>/when applicable - •PR/Commit: reference if known; otherwise
- - •Root cause summary: 1–2 lines max, actionable
Bug logging behavior by phase
- •Analyze/Design/QA phases: if you find an issue, log it even if no code changed.
- •Implementation phase: if you notice a bug or regression, log it immediately before continuing.
- •Deployment/Maintenance: production incidents must be logged with
Detected by = user:prodorsystem:monitoringwhere appropriate.
Bug follow-up artifact (optional, but encouraged for S0/S1)
For severe bugs (S0/S1), create a short writeup:
- •
docs/quality/bugs/BUG-####.md
Including:
- •reproduction steps
- •expected vs actual
- •suspected injection phase reasoning
- •fix plan
- •prevention note (what phase should catch this next time)
Completion rule
A feature cannot be considered “QA Approved” if there are any S0/S1 open bugs linked to that feature unless explicitly waived in the QA report.
Bug phase classification
When logging any bug or issue:
- •You MUST use the bug-phase-classification skill
- •Apply it to determine:
- •Detected phase
- •Injected phase (suspected)
Do not invent your own heuristics outside this skill. If uncertain, follow the skill and document uncertainty in Notes.