/investigate

ผู้อ่าน: Coding agent และผู้ดูแล integration คำสั่ง CLI และ schema ด้านล่างเป็นเอกสารระบบ ไม่ใช่รายการที่ผู้ใช้ต้องทำเอง ผู้ใช้เริ่มที่ เริ่มใช้งาน

พูดง่าย ๆ: Investigate คือขั้นค้นคว้าที่เป็นตัวเลือก ใช้เมื่อคุณยังบอกไม่ได้ว่าควรเปลี่ยนอะไร คุณบอกคำถามหรือเรื่องที่ตัดสินใจไม่ได้ agent จะอ่านโค้ด (ไม่แก้โค้ดของ product) และ harness บันทึกสิ่งที่ตรวจไว้ ผลที่ได้คือรายงานสั้น ๆ ที่แยกข้อเท็จจริงที่ยืนยันแล้วออกจากข้อสันนิษฐาน และจบด้วยหนึ่งในสามข้อสรุป: พร้อมไป /change, ต้องให้คุณตัดสินใจ หรือไม่คุ้มที่จะเปลี่ยน ถ้าคำขอชัดอยู่แล้ว ข้ามไป /change ได้เลย

สำหรับ agent และผู้ดูแล integration

/investigate <ปัญหาหรือการตัดสินใจ> [--compare]

ใช้ขั้นนี้เมื่อคุณยังรู้ไม่พอที่จะเขียนข้อตกลงที่เชื่อถือได้เท่านั้น มันเป็นขั้นเดียวในวงจรที่เป็นตัวเลือก และการหยิบมาใช้โดยอัตโนมัติมีแต่จะเพิ่มเวลา

เหตุผลที่ควรใช้จริง ๆ

ยังไม่รู้ต้นตอของปัญหา
มีหลายแนวทางที่ tradeoff ต่างกันอย่างมีนัยสำคัญ
ข้อจำกัดเรื่อง compatibility หรือ migration ยังไม่ชัด
เป็นเส้นทางโค้ด brownfield ที่ไม่คุ้นเคย
เป็น external API ที่ยังไม่ได้อ่านเอกสารตาม version, success path หรือ failure behavior

เริ่มจากสิ่งที่ยังไม่รู้

เขียน input เป็นการตัดสินใจที่คุณตัดไม่ลง ไม่ใช่คำสั่งให้ไป implement อะไร

/investigate why profile updates occasionally overwrite newer data

ถ้าเป็น change ที่มีอยู่แล้ว ให้ใส่ ID พร้อมคำถามใหม่

/investigate add-profile: should updates use last-write-wins or optimistic locking?

ได้อะไรกลับมา

agent จะอ่านโค้ดที่เกี่ยวข้องแล้วแยกผลลัพธ์ออกเป็น

ข้อเท็จจริงที่ยืนยันจากโค้ดจริง
สมมติฐาน ที่ยังไม่ได้พิสูจน์ ซึ่งระบุ experiment ที่จะใช้ทดสอบเป็นการตรวจต่อ (experimentKeys) ได้
ข้อจำกัด และขอบเขตที่ได้รับผลกระทบ
ตัวเลือก พร้อม tradeoff
สิ่งที่ยังไม่รู้ ซึ่งต้องให้คุณตัดสินใจ

การแยกนี้คือคุณค่าทั้งหมดของขั้นนี้ เพราะสิ่งที่นำเสนอเป็นข้อเท็จจริงกับสิ่งที่เป็นแค่การเดา นำไปสู่ change ที่ต่างกันมาก และการยุบสองอย่างนี้รวมกันคือวิธีที่ข้อตกลงห่วย ๆ เกิดขึ้น

มันจะจบด้วยหนึ่งในสามอย่างนี้เท่านั้น

ready for /change
needs user decision
not worth changing

not worth changing เป็นผลลัพธ์ที่ถูกต้องและมีประโยชน์

Agent เริ่มจาก claude-foundation investigate --template เก็บ record ที่ openspec/investigations/<id>.json และเรียก claude-foundation investigate <record.json> หลังอ่านหลักฐานแต่ละ batch Harness จะค้นและ hash source ที่ เกี่ยวข้อง ตรวจ link ของ fact, hypothesis และ recommendation เก็บ metrics กับ no-progress state แล้วคืน EDIT, ASK_USER หรือ DONE พร้อม resume route source ใหม่ที่ค้นพบจะถูกยืนยันโดยอัตโนมัติและยังถูก hash เพื่อตรวจความสดใหม่ ทุก fact ต้องอ้าง source ที่อยู่ใน inventory และรายงานจะแสดง source ที่ค้นพบแต่ยัง ไม่มี fact อ้างอิง decision ที่ยังเปิดอยู่ทำให้ข้อสรุปเป็น needs user decision และ record ที่สรุปครบพร้อม change intent จบได้ในรอบเดียว เมื่อไม่คืบหน้าซ้ำ ระบบจะถามผู้ใช้เฉพาะเมื่อขั้นตอนที่ซ้ำคือคำถามถึงผู้ใช้ ส่วนปัญหาของ sandbox หรือการค้นหา source จะส่งให้ harness

แต่ละ batch สร้างรายงานที่อ่านได้ที่ openspec/investigations/<id>.report.md แสดงข้อสรุป เหตุผล แหล่งอ้างอิง สมมติฐานที่ทดสอบ ทางเลือก สิ่งที่ยังไม่รู้ และ การตัดสินใจถัดไป Agent เขียนในภาษาของผู้ใช้และส่งสรุปสั้นพร้อมลิงก์รายงาน JSON record ยังคงใช้ร่วมกับระบบเดิมได้ รายงานที่สร้างไม่เป็น source ของการสำรวจ และไม่เริ่ม Change หากสร้างรายงานไม่ได้ ระบบรักษางานสำรวจไว้และให้ agent ทำต่อ โดยไม่แสดงรายงานเก่าเป็นผลปัจจุบัน

หากคำถามเกิดจาก Build หรือ Prove workspace ที่มีอยู่ ให้ตั้ง field activeChange ใน record เป็น change ID นั้น source path จะอ้างอิงจาก isolated workspace ที่ active และ handoff จะผูก source root, base และ identity หาก sandbox หาย stale หรืออ่านไม่ได้ ตั้งแต่รอบแรกจะเป็นงานซ่อมของ harness (repair-harness) พร้อมคำสั่ง record เดิมที่ใช้ resume โดยไม่ย้อนอ่าน main checkout

เขียนอะไรได้บ้าง

ขั้นสำรวจเป็น read-only ต่อ product code และ formal change packet งานเขียนปกติ ของ agent มีเพียง JSON record กับ note ที่เลือกสร้างใต้ openspec/investigations/; harness เท่านั้นที่เขียน state ใต้ .foundation/investigations/ และรายงาน <id>.report.md ที่สร้างจาก state note <id>.md ที่ผู้ใช้เขียนไว้จะถูกเก็บรักษา

โหมดเปรียบเทียบ

สำหรับทางเลือกด้าน experience, API หรือสถาปัตยกรรมที่ยังตัดสินไม่ได้จริง ๆ ให้เติม --compare

/investigate dashboard filter interaction --compare

จะได้ทางเลือกแบบเบาและใช้แล้วทิ้ง 3–5 แบบใต้ .foundation/prototypes/<id>/ ในโหมดนี้ agent จึงเขียนเพิ่มได้ เฉพาะ ใน prototype directory โดยไม่แตะ product code หรือ formal change packet

Investigation record ใช้ mode: "compare": แต่ละทางเลือกมี finding, trade-off, source และ prototypePaths และ agent เขียน prototype ได้เฉพาะ path ที่ประกาศไว้เท่านั้น เมื่อสรุปแล้ว selection ใน record จะระบุทางเลือกที่เลือก เหตุผล และเหตุที่ตัดทางเลือกอื่นแต่ละตัว และ report ที่สร้างขึ้นจะแสดงไว้ เมื่อหลักฐานตัดสินไม่ได้ มันจะถามคุณแทนที่จะเลือกเอง

ไปต่อที่ข้อตกลงพร้อมแนบตัวเลือกที่เลือกไว้

/change <intent> --prototype-selection <selection-path>

/change จะสรุปการตัดสินใจนั้นลงใน proposal และ design แต่จะไม่ถือว่าตัวเลือกหรือ artifact ของมันเป็นหลักฐาน ผล ready-for-change จาก runtime จะมี handoff ที่ผูก digest ให้ agent คัดลอก เข้า field investigation ของ semantic draft; Change จะปฏิเสธหาก state หรือ source ที่เลือกเปลี่ยนไป สำหรับ integration บันทึกจะเก็บ source กับ version ของเอกสารให้ชัด /change จึงบังคับ scenario ทั้ง success และ failure ส่วน API ที่ยังไม่อ่านหรือไม่มี version เป็น research boundary ไม่ใช่ contract ที่เดาได้