debug-issue

Instructions

You are investigating a user-submitted issue. The issue ID was provided as an argument.

Step 1: Start from the reported issue database

The reported issue database is the source of truth. Do not start from Linear or GitHub unless the issue note links there.

python3 scripts/issues.py show $ARGS --env prod
python3 scripts/issues.py findings $ARGS --env prod

If the issue is known to be from dev, use --env dev. The findings command creates a local-only, gitignored note at docs/findings/issues/<env>/<YYYY>/...md. Update this note with the first anomaly, root-cause hypothesis, related reports, attempts, tests, and final status before changing product code. Do not store reported-issue findings elsewhere.

For production issues, inspect the production code on main before using the current worktree: run git fetch origin main:refs/remotes/origin/main, read suspect files with git show origin/main:<path>, and only then compare with dev. Use dev only to check whether it is also susceptible to the same issue/bug/behavior or whether it already contains a fix.

Use these workflow helpers before raw debug commands:

python3 scripts/issues.py list --env prod --limit 20
python3 scripts/issues.py cluster --env prod --limit 100
python3 scripts/issues.py timeline $ARGS --env prod --compact
python3 scripts/issues.py mark $ARGS --env prod --status investigating

Step 2: Delegate forensics to the issue-forensics subagent

Launch the issue-forensics agent with this prompt:

Investigate issue $ARGS. Use scripts/issues.py show, scripts/issues.py timeline, and the created findings note as the workflow entry points. Run raw debug.py issue only when the wrapper lacks a needed low-level view. For prod issues, inspect suspect code on origin/main first after git fetch origin main:refs/remotes/origin/main; use dev only as a susceptibility/fix comparison. Follow any trace IDs, identify the first anomaly, and return the structured JSON + narrative. Use --env prod when this is a prod issue.

The agent runs all debug.py commands, correlates browser↔backend events, git-blames suspects, and returns a compact report with first_anomaly, root_cause_hypothesis, suspect_files[], reproduction_steps, and related_recent_commits.

If the symptom looks like encryption / decryption / chat sync: after issue-forensics returns, also launch encryption-flow-tracer with the first anomaly message as the symptom — it will pinpoint the broken invariant in the E2EE/sync data flow.

Do NOT run raw debug.py commands yourself unless scripts/issues.py cannot expose the needed low-level view — raw timelines flood main context. Trust the agents' compact reports.

Step 3: Write the Fix

Using the agent's suspect_files and narrative:

1. Read the suspect code (20–40 lines around the reported line)
2. Confirm the hypothesis fits
3. Update the findings note with the confirmed hypothesis and intended test
4. Apply the minimal fix

Step 4: Debugging Attempt Limit

2 tries max with the same approach. If the agent's first hypothesis fails, re-launch it with your new context ("the fix at X did not resolve the issue because Y — look for a different root cause"). On the 3rd attempt, STOP and load sessions.py context --doc debugging.

Step 5: After Fix Confirmed

Update the findings note and mark it verified:

python3 scripts/issues.py mark $ARGS --env prod --status verified

Only delete the issue report after the user confirms the fix is verified:

docker exec api python /app/backend/scripts/debug.py issue $ARGS --delete --yes

Default Assumptions

• Issues are on the prod server unless the user says dev or the report was discovered in dev
• Check if another session is rebuilding Docker containers if services appear down