debug-flight-recorder

name	debug-flight-recorder
description	Add contextual logs along a bug's call path, run the repro, collect logs, then auto-remove (marker-comment cleanup). Triggers: "debug with logs", "add console logs", "flight recorder", "bug khong tai hien", "khong biet loi o dau", "trace bug".

debug-flight-recorder — Instrument, Repro, Collect, Revert

Step 0 — Preflight

# clean working tree required — we'll add logs then remove them
git status --porcelain

If dirty → "Anh đang có thay đổi chưa commit. Stash hoặc commit trước rồi mới debug nha (để em revert log sau mà không đụng code anh đang viết)."

Capture snapshot SHA:

git rev-parse HEAD > .taw/debug-sha.txt

Step 1 — Understand the bug

Ask the user:

Mô tả bug (ngắn thôi):
  1. Steps to reproduce (cách tái hiện)?
  2. What should happen (đáng lẽ gì xảy ra)?
  3. What actually happens (thực tế gì xảy ra)?
  4. Có error message không? (paste vào cũng được)

Store in .taw/debug-session.json:

{
  "bug": "<short>",
  "repro_steps": "<list>",
  "expected": "...",
  "actual": "...",
  "error": "<if any>",
  "started_at": "<ISO>",
  "state": "planning"
}

Step 2 — Identify instrument points

From the user's description, grep for relevant files:

# by keyword from bug description
git grep -n --files-with-matches 'checkout' app/ lib/ components/ 2>/dev/null
# by error message (if any)
git grep -n --files-with-matches '<error snippet>' 2>/dev/null

Pick 3-8 strategic points (never more — cognitive load):

• Entry: route handler or form submit
• Key branching: if that decides success vs error
• External calls: fetch(, await supabase, stripe.
• State mutations: setState(, dispatch(
• Right before/after the line that crashes

Present candidates to user:

Em sẽ thêm log ở 5 chỗ nghi ngờ:
  1. app/checkout/page.tsx:34     — form submit handler
  2. app/api/checkout/route.ts:12 — entry route handler
  3. lib/cart.ts:56               — calcTotal
  4. lib/stripe.ts:23             — session create
  5. lib/supabase.ts:89           — save order

Gõ:
  y        → thêm log và chạy repro
  skip 3   → bỏ chỗ số 3
  add <path>:<line> → thêm chỗ khác
  cancel   → huỷ

Step 3 — Instrument (marker-based)

Every log uses this exact marker so cleanup is safe:

// [TAW-DEBUG-FR] marker — removed automatically by debug-flight-recorder

For each point, insert ONE log line with rich context. Pattern by site type:

Function entry

export function calcTotal(items: Item[]) {
  console.log('[TAW-DEBUG-FR] lib/cart.ts:calcTotal entry', { items_count: items.length, items_sample: items.slice(0,2) }); // [TAW-DEBUG-FR] marker
  // ... existing body
}

Before external call

console.log('[TAW-DEBUG-FR] app/api/checkout/route.ts:pre-supabase', { user_id: user?.id, cart: body }); // [TAW-DEBUG-FR] marker
const { data, error } = await supabase.from('orders').insert(body);
console.log('[TAW-DEBUG-FR] app/api/checkout/route.ts:post-supabase', { data, error }); // [TAW-DEBUG-FR] marker

Inside conditional

if (session.status === 'complete') {
  console.log('[TAW-DEBUG-FR] route:branch=complete', { session_id: session.id }); // [TAW-DEBUG-FR] marker
  // ...
} else {
  console.log('[TAW-DEBUG-FR] route:branch=incomplete', { status: session.status, reason: session.last_error }); // [TAW-DEBUG-FR] marker
  // ...
}

Before throw / return

console.log('[TAW-DEBUG-FR] pre-throw', { err, ctx }); // [TAW-DEBUG-FR] marker
throw err;

Scrub sensitive values

Never log: passwords, full tokens, credit card, session secrets. Truncate: token?.slice(0,8) + '...'.

Track touched files in .taw/debug-files.txt:

app/checkout/page.tsx
app/api/checkout/route.ts
lib/cart.ts
lib/stripe.ts

Update session state:

{"state": "instrumented", "points": 5}

Step 4 — Run repro

# detect dev server
pgrep -f 'next dev' >/dev/null && echo "dev server running" || echo "start dev server: npm run dev"

Emit (VN):

Đã thêm log vào 5 chỗ. Giờ:
  1. Mở terminal khác, chạy `npm run dev` nếu chưa
  2. Tái hiện bug (theo steps anh mô tả)
  3. Copy output console trong terminal dev server + browser console (nếu có)
  4. Paste vào đây, hoặc gõ `dev-log` để em tail dev.log

Xong gõ: `done`

Option: if user has npm run dev piped to dev.log:

tail -f dev.log | command grep '\[TAW-DEBUG-FR\]' &

Step 5 — Analyze logs

User pastes log output (or points to file). Parse:

1. Group by site ID ([TAW-DEBUG-FR] <file>:<marker>)
2. Build timeline: which sites fired, in what order
3. Compare to expected flow (from Step 1 user description)

Render (VN):

Phân tích logs:

Timeline:
  1. ✓ app/checkout/page.tsx:submit      (13:42:01)
  2. ✓ app/api/checkout/route.ts:entry   (13:42:01)
  3. ✓ lib/cart.ts:calcTotal entry        (13:42:01) — items_count: 3
  4. ✓ route:pre-supabase                 (13:42:02)
  5. ✗ route:post-supabase                 — không thấy log này
  6. ✗ route:branch=complete              — không vào nhánh success

Kết luận nghi vấn:
  Supabase insert không return → có thể hang, timeout, hoặc throw.
  Kiểm tra:
    - RLS policy có cho user insert không?
    - Supabase URL + anon key đúng không?
    - Network tab browser có thấy request 401/500 không?

Step 6 — Propose fix

Based on timeline, emit specific next step:

• Last site that fired + didn't reach next → root cause lives between them
• Propose: re-run with MORE logs at suspected point, OR apply fix directly

If user wants to fix now, hand off to @branches/fix.md with the diagnostic in context.

Step 7 — Cleanup (ALWAYS runs, even on error)

# find all files with the marker
command grep -rl '\[TAW-DEBUG-FR\]' app/ components/ lib/ 2>/dev/null > .taw/debug-mark-files.txt

# remove every line containing the marker
while read f; do
  # preserve original
  cp "$f" "$f.bak"
  # strip lines containing the marker
  command grep -v '\[TAW-DEBUG-FR\]' "$f.bak" > "$f"
  rm "$f.bak"
done < .taw/debug-mark-files.txt

Verify clean:

command grep -rn '\[TAW-DEBUG-FR\]' . 2>/dev/null | command grep -v '.taw/'
# should be empty

If any remain → emit paths + ask user to manually confirm cleanup before committing.

Run npm run build to confirm cleanup didn't break anything:

npm run build 2>&1 | tail -5

If build broke (rare — usually syntax from a misplaced comma): revert:

git reset --hard $(cat .taw/debug-sha.txt)

Step 8 — Summary + done

Debug session xong.

Điểm nghi vấn: <file:line> — <reason>
Gợi ý sửa: <1 sentence>

Cleanup:
  ✓ Xoá 5 log marker
  ✓ Build vẫn xanh
  ✓ Working tree sạch như trước

Gõ:
  $taw fix     → em fix chỗ tìm ra luôn
  thoat        → để anh tự sửa

Clean up:

rm -f .taw/debug-session.json .taw/debug-sha.txt .taw/debug-files.txt .taw/debug-mark-files.txt

Gotchas

• Marker collision — cực hiếm nhưng nếu user đã có TAW-DEBUG-FR trong code (why?) → refuse, ask to rename
• Minified builds — logs go to server console (for route handlers) or browser console (for client components). Make sure user knows where to look
• Async race conditions — order of log lines may not match code order for Promise.all / concurrent awaits. Use timestamps
• Logging inside loops — adds thousands of lines. Sample: if (i < 3 || i % 100 === 0) console.log(...)
• Sensitive data leaked into logs — always truncate tokens, hash emails, never full passwords. If bug IS about auth, extra careful

Constraints

• NEVER leave marker comments in committed code — Step 7 cleanup is MANDATORY
• Max 8 instrument points per session — more = cognitive overload, worse signal
• Require clean working tree at start — revert path must stay safe
• Never log: passwords, full tokens (>8 chars), CC, session secrets, PII
• Cleanup MUST run even if user Ctrl-C — write cleanup as trap or always-final step
• If build breaks after cleanup (rare) → hard reset to snapshot SHA
• All logs use console.log('[TAW-DEBUG-FR] ...') format — non-negotiable (cleanup depends on it)