Bug Tracking
Guideline
- Create a detailed fix plan for each bug - the plan must contain test approach and validation steps - execute the plan and validate the fix when all elements are in place.
- Any issues found must be fixed and the fix plan must be updated accordingly.
- Issues found during testing must be fixed and the fix plan must be updated accordingly.
- Each bug should be moved to archive when tested and closed as the associated plan.
- Use interactive shell to validate the output of the tool - you must verify the actual terminal output.
- Check code quality with each tool run separately (do not chain them with
; or &&):
go vet ./...staticcheck ./...gocognit -over 15 .gocyclo -over 12 .go test -count=1 -race -cover ./...
Fix any new issues introduced by the change. Pre-existing warnings are acceptable only if they are unrelated to the change and explicitly noted.
At the end of the session - the bug list should be empty and this file should only contain the guidelines for bug reporting.
If new items are added, restart the process.
Workflow for bugs
- Reproduce the failure before editing — ideally a command or script that triggers it on demand.
- State the observed failure exactly (command + output).
- Localize to the smallest region — ideally the specific lines — before editing. Precise localization is the strongest predictor of a correct fix.
- Change one hypothesis at a time.
- Prefer the minimal fix over a broad refactor.
- Verify against the original failing command before declaring done.
- Run the code-quality checks from guideline #6 separately and confirm the fix does not introduce new violations.
- Move the bug list to
docs/archive/bugs.<fixdate>.md when all items are closed.