Prompt file imported from jimzandueta/nestjs-http-server-boilerplate-codex-ai-assisted (.codex/prompts/debug.md). Fill in {{SYMPTOM}}, {{ENVIRONMENT}}, {{ERROR_DETAILS}}, {{REPRO_STEPS}}, {{RECENT_CHANGES}} before use. Copyright stays with the author.

Prompt: Debug

Inputs

• Symptom: {{SYMPTOM}} (what's happening vs. what's expected)
• Environment: {{ENVIRONMENT}} (local, dev, staging, production)
• Error message / stack trace: {{ERROR_DETAILS}}
• Reproduction steps: {{REPRO_STEPS}}
• Recent changes: {{RECENT_CHANGES}} (deployments, config changes, dependency updates)

Instructions

• Follow .codex-generic/RULES.md.
• Read memory/learned-patterns.md — the issue may match a known pattern.
• Read memory/decisions.md — recent decisions may explain the behavior.
• Reproduce first: Confirm the exact conditions that trigger the bug.
• Trace the code path: Follow from symptom to root cause. Use structured logging, breakpoints, or bisect.
• Write a failing test: Before applying any fix, write a test that demonstrates the bug.
• Apply the minimal fix: Change the least amount of code necessary.
• Verify: Run the failing test (should now pass) and the full test suite (no regressions).
• Run checklists/pre-commit.md before finishing.
• If the bug reveals a new pattern or anti-pattern, update memory files.

Diagnosis Techniques

1. Error message analysis: Parse the error message for the exact failure point.
2. Log review: Filter logs by service, time window, and correlation ID.
3. Git bisect: Find the exact commit that introduced the regression.
4. Input reduction: Simplify the reproducing input to the minimal case.
5. Boundary analysis: Test edge cases near the failure point (null, empty, max, type mismatch).
6. Dependency check: Verify versions of dependencies match expected (lock file drift?).

Patterns to Consult

• patterns/error-handling.md — expected error handling strategy
• patterns/configuration.md — if the issue might be config-related
• memory/learned-patterns.md — known patterns and conventions