triage

Files (3)

• AGENT-BRIEF.md
• OUT-OF-SCOPE.md
• SKILL.md

SKILL.md (first lines)

# 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.md) — วิธีเขียน agent brief ที่คงทน
- [OUT-OF-SCOPE.md](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](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](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

```markdown
## 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 ก่อนหน้าอยู่ ให้อ่าน เช็คว่าผู้รายงานตอบคำถามที่ค้างอยู่บ้างหรือยัง แล้วนำเสนอภาพล่าสุดก่อนทำต่อ อย่าถามคำถามที่ได้ข้อสรุปแล้วซ้ำ

From Boom-Vitt/skills-thai, MIT.

More from Boom-Vitt/skills-thai