Triage

พา issue บน issue tracker ของโปรเจกต์เดินผ่าน state machine (เครื่องจักรสถานะที่กำหนดว่าย้ายจาก state ไหนไป state ไหนได้) เล็ก ๆ ของ triage role

ถ้า repo นี้ปฏิบัติกับ external pull request เป็นช่องทางรับคำขอด้วย (ดู config ของ issue-tracker) triage ก็ครอบคลุมมันเช่นกัน: PR คือ issue ที่มี code แนบมา — role เดียวกัน state เดียวกัน machine เดียวกัน โดยมีจุดต่างไม่กี่จุดที่กำกับไว้ว่า "สำหรับ PR" ด้านล่าง ถ้าเจอ #42 เปล่า ๆ ให้ resolve ว่าเป็น issue หรือ PR ตาม config ของ tracker

ทุก comment หรือ issue ที่โพสต์ลง issue tracker ระหว่าง triage ต้อง ขึ้นต้นด้วย disclaimer นี้:

> *This was generated by AI during triage.*

เอกสารอ้างอิง

• AGENT-BRIEF.md — วิธีเขียน agent brief ที่คงทน
• OUT-OF-SCOPE.md — knowledge base .out-of-scope/ ทำงานยังไง

Role

role ประเภท หมวดหมู่ สองตัว:

• bug — มีอะไรบางอย่างพัง
• enhancement — feature ใหม่หรือการปรับปรุง

role ประเภท state ห้าตัว:

• needs-triage — maintainer ต้องประเมิน
• needs-info — รอข้อมูลเพิ่มจากผู้รายงาน
• ready-for-agent — spec ครบถ้วนแล้ว พร้อมให้ agent แบบ AFK รับไปทำ
• ready-for-human — ต้องให้มนุษย์ implement
• wontfix — จะไม่ดำเนินการ

สำหรับ PR ให้อ่าน state ชุดเดียวกันโดยเทียบกับ code ที่แนบมา: ready-for-agent แปลว่ามี brief แนบแล้วและ agent ควรทำขั้นถัดไปกับ diff; ready-for-human แปลว่าพร้อมให้มนุษย์ merge

issue ที่ triage แล้วทุกตัวควรมี role หมวดหมู่หนึ่งตัวและ state role หนึ่งตัวพอดี ถ้า state role ขัดแย้งกัน ให้ flag ไว้แล้วถาม maintainer ก่อนทำอย่างอื่น

ชื่อพวกนี้คือชื่อ role มาตรฐาน — string ของ label ที่ใช้จริงใน issue tracker อาจต่างออกไป mapping ควรถูกส่งมาให้คุณแล้ว — ถ้ายังไม่มี ให้รัน /setup-matt-pocock-skills

การเปลี่ยน state: issue ที่ยังไม่มี label ปกติจะไป needs-triage ก่อน จากตรงนั้นค่อยย้ายไป needs-info, ready-for-agent, ready-for-human หรือ wontfix ส่วน needs-info จะกลับไป needs-triage เมื่อผู้รายงานตอบกลับ maintainer สามารถ override ได้ตลอดเวลา — ถ้าการเปลี่ยน state ไหนดูผิดปกติ ให้ flag แล้วถามก่อนดำเนินการต่อ

การเรียกใช้

maintainer เรียก /triage แล้วอธิบายสิ่งที่ต้องการเป็นภาษาธรรมชาติ ตีความคำขอแล้วลงมือทำ ตัวอย่าง:

• "ขอดูทุกอย่างที่รอให้จัดการ"
• "มาดู #42 กัน" (issue หรือ PR)
• "ย้าย #42 ไป ready-for-agent"
• "มีอะไรพร้อมให้ agent หยิบไปทำบ้าง?"

แสดงสิ่งที่รอการจัดการ

query issue tracker แล้วนำเสนอสาม bucket เรียงจากเก่าสุดก่อน:

1. ยังไม่มี label — ไม่เคยถูก triage
2. needs-triage — กำลังประเมินอยู่
3. needs-info ที่ผู้รายงานมีความเคลื่อนไหวหลัง triage notes ล่าสุด — ต้องประเมินใหม่

เมื่อ PR อยู่ในขอบเขต ให้รวม external PR เข้า bucket พวกนี้ด้วย และติดป้ายแต่ละบรรทัดว่า [PR] หรือ [issue] ขั้นตอนการค้นหาจะโชว์เฉพาะ PR ภายนอก เท่านั้น (config ของ tracker กำหนดว่าใครนับเป็นภายนอก) — PR ที่ collaborator กำลังทำค้างอยู่ไม่ใช่งาน triage filter นี้ใช้เฉพาะตอนค้นหา; PR ที่ถูกระบุชื่อมาตรง ๆ ต้อง triage เสมอไม่ว่าใครเป็นคนเขียน

แสดงจำนวนและสรุปหนึ่งบรรทัดต่อรายการ แล้วให้ maintainer เป็นคนเลือก

Triage issue หรือ PR ที่เจาะจง

1. เก็บ context อ่าน issue หรือ PR ให้ครบ (เนื้อหา, comment, label, ผู้เขียน, วันที่; ถ้าเป็น PR อ่าน diff ด้วย) parse triage notes ก่อนหน้าเพื่อจะได้ไม่ถามคำถามที่ได้ข้อสรุปแล้วซ้ำ สำรวจ codebase โดยใช้ domain glossary ของโปรเจกต์ และเคารพ ADR ในบริเวณนั้น รันการตรวจสองอย่างกับ codebase: (a) ความซ้ำซ้อน — ค้นหา implementation ที่มีอยู่แล้วของพฤติกรรมที่ถูกขอ โดยค้นตาม concept ของ domain (ไม่ใช่แค่ตามถ้อยคำในคำขอ) และรายงานว่าไปค้นที่ไหนมาบ้าง ถ้าเจอ แปลว่าเป็น wontfix แบบทำไปแล้ว (ขั้นที่ 5) (b) เคยถูกปฏิเสธมาก่อน — อ่าน .out-of-scope/*.md แล้วหยิบอันที่คล้ายกับคำขอนี้ขึ้นมาแสดง
2. เสนอคำแนะนำ บอก maintainer ว่าแนะนำหมวดหมู่และ state ไหนพร้อมเหตุผล บวกสรุป codebase สั้น ๆ ที่เกี่ยวข้องกับคำขอ — รวมถึงว่ามัน implement ไปแล้วหรือยัง แล้วรอฟังทิศทาง
3. ตรวจสอบข้อกล่าวอ้าง ก่อนจะ grill ใด ๆ ให้เช็คว่าข้อกล่าวอ้างยืนได้จริง ถ้าเป็น bug ให้ reproduce จากขั้นตอนของผู้รายงาน ถ้าเป็น PR ให้ยืนยันว่า diff ทำตามที่อ้างจริง — checkout ออกมา รัน test หรือคำสั่งที่เกี่ยวข้อง แล้วรายงานผลที่เกิดขึ้น: ยืนยันได้ (พร้อม code path), ล้มเหลว หรือรายละเอียดไม่พอ (สัญญาณ needs-info ที่ชัดมาก) การตรวจสอบที่ยืนยันได้ทำให้ agent brief แข็งแรงขึ้นเยอะ
4. Grill (ถ้าจำเป็น) ถ้าคำขอยังต้องขัดเกลาให้เป็นรูปเป็นร่าง ให้รัน skill /grilling กับ /domain-modeling คู่กัน — grill มันให้เข้ารูปทีละคำถาม ลับคม domain term และอัปเดต CONTEXT.md/ADR ไปพร้อมกันเมื่อการตัดสินใจตกผลึก
5. นำผลลัพธ์ไปใช้:
   • ready-for-agent — โพสต์ comment ที่เป็น agent brief (AGENT-BRIEF.md)
   • ready-for-human — โครงสร้างเดียวกับ agent brief แต่ระบุด้วยว่าทำไม delegate ไม่ได้ (ต้องใช้วิจารณญาณ, ต้องเข้าถึงระบบภายนอก, การตัดสินใจด้าน design, ต้อง test ด้วยมือ)
   • needs-info — โพสต์ triage notes (template ด้านล่าง)
   • wontfix — ปิด โดย comment ขึ้นอยู่กับ เหตุผล:
     • ทำไปแล้ว — การเปลี่ยนแปลงนั้นมีอยู่ใน codebase แล้ว ชี้ไปยังที่ที่มันอยู่; ห้าม เขียนลง .out-of-scope/ (KB นั้นมีไว้สำหรับคำขอที่ถูกปฏิเสธ ไม่ใช่อันที่สร้างเสร็จแล้ว)
     • ปฏิเสธ (bug) — อธิบายอย่างสุภาพ แล้วปิด
     • ปฏิเสธ (enhancement) — เขียนลง .out-of-scope/ ใส่ link ถึงมันใน comment แล้วปิด (OUT-OF-SCOPE.md)
   • needs-triage — ติด role ไว้ จะ comment ด้วยก็ได้ถ้ามีความคืบหน้าบางส่วน

Override state แบบเร็ว

ถ้า maintainer บอกว่า "ย้าย #42 ไป ready-for-agent" ให้เชื่อเขาแล้วติด role ตรง ๆ เลย ยืนยันสิ่งที่กำลังจะทำ (เปลี่ยน role, comment, ปิด) แล้วลงมือ ข้ามการ grill ถ้าย้ายไป ready-for-agent โดยไม่ผ่าน session grill ให้ถามว่าอยากให้เขียน agent brief ไหม

Template สำหรับ needs-info

## Triage Notes

**What we've established so far:**

- point 1
- point 2

**What we still need from you (@reporter):**

- question 1
- question 2

เก็บทุกอย่างที่ได้ข้อสรุประหว่าง grill ไว้ใต้ "established so far" เพื่อไม่ให้งานสูญหาย คำถามต้องเจาะจงและลงมือตอบได้จริง ไม่ใช่ "please provide more info"

กลับมาทำ session ก่อนหน้าต่อ

ถ้า issue หรือ PR มี triage notes ก่อนหน้าอยู่ ให้อ่าน เช็คว่าผู้รายงานตอบคำถามที่ค้างอยู่บ้างหรือยัง แล้วนำเสนอภาพล่าสุดก่อนทำต่อ อย่าถามคำถามที่ได้ข้อสรุปแล้วซ้ำ