[🛠] Operations Automation #4: Mencegah status stale dengan mengubah lebih sedikit dokumen

✨ Ringkasan GPT-5.6 Sol

Catatan tentang menata ulang alur pembaruan dokumentasi dengan meninggalkan penyalinan perubahan status ke banyak dokumen, lalu menetapkan satu owner untuk status yang mudah berubah, downstream bersyarat, dan checkpoint per phase.

Semakin banyak dokumen diperbarui, semakin bercabang status saat ini

Setelah pekerjaan panjang mengalami compaction atau diserahkan ke session lain, pernah terjadi tugas berikutnya yang tertulis di dokumen lama dianggap sebagai status saat ini. Untuk mencegah masalah ini, selama beberapa waktu saya memperbaiki semua dokumen yang tampak terkait setiap kali status berubah.

Fakta penyelesaian dan tugas berikutnya yang sama saya tulis berulang kali di README, router dokumen, requirements, current direction, Runbook, dan TODO. Selama tidak ada dokumen yang terlewat, cara itu terasa aman.

Namun, sejak satu perubahan status ditulis di enam tempat, keenam tempat itu harus terus dijaga agar tetap identik. Satu dokumen tertinggal pada status sebelum deploy, sedangkan dokumen lain menyatakan verifikasi pada perangkat nyata sudah selesai. Memperbarui banyak dokumen bukannya mencegah status stale, tetapi justru menciptakan status stale yang baru.

Setiap verifikasi kecil selesai, beberapa dokumen kembali diubah dan commit baru dibuat. Akibatnya, Git history pun terpecah-pecah. Jumlah sinkronisasi kalimat terlihat lebih jelas daripada titik ketika implementasi benar-benar selesai.

Status yang mudah berubah hanya dimiliki oleh satu dokumen

Masalahnya bukan jumlah dokumen, melainkan fakta yang sama dimiliki oleh beberapa dokumen. Karena itu, saya terlebih dahulu menetapkan satu owner untuk setiap jenis fakta.

Fakta yang berubah	owner	Syarat untuk mengubah dokumen lain
Runtime saat ini, blocker, phase, dan tugas berikutnya	canonical current-state snapshot	Jangan disalin ke dokumen lain
Keputusan produk yang stabil, jalan pintas yang dilarang, dan Goal aktif	Dokumen current-direction	Hanya ketika keputusan produk atau Goal itu sendiri berubah
Perilaku, data, izin, dan acceptance	requirements atau contract	Hanya ketika kontrak perilaku pengguna atau sistem berubah
Prosedur operasional, gate, rollback, dan recovery	Runbook	Hanya ketika prosedur yang harus diikuti operator berubah
Relasi dokumen, tahap produk, dan titik masuk eksekusi	README atau router	Hanya ketika jalur penelusuran atau relasi produk berubah
Perintah terperinci, log, dan verifikasi worker	report, artifact, dan Git evidence	Dokumen aggregate hanya menyimpan kesimpulan dan tautan bukti

Intinya adalah memisahkan terkait dari memiliki. Selesainya deploy tidak mengharuskan requirements diubah. Jika prosedur rollback operasional berubah selama deploy, Runbook diperbarui. Jika kontrak perilaku ikut berubah, barulah requirements diperbarui.

README dan router juga tidak lagi mengikuti revision saat ini, status perangkat, atau tugas berikutnya. Dokumen-dokumen ini hanya menunjukkan secara stabil apa yang harus dibaca dan dari mana eksekusi harus dimulai.

Pembaruan langsung dipisahkan dari durable checkpoint

Satu owner bukan berarti pembaruan dokumen ditunda sampai phase berakhir. Ketika ada bukti baru atau status Runtime, blocker, prioritas, maupun tugas berikutnya berubah, canonical current-state snapshot langsung diperbaiki sebelum implementasi selanjutnya. Dengan begitu, meskipun konteks mengalami compaction atau diserahkan di tengah pekerjaan, session berikutnya dapat memulihkan status nyata dari satu tempat.

Sebaliknya, commit tidak dibuat setiap kali satu baris status berubah. Current-state diperiksa satu kali dan checkpoint hanya dibuat pada batas yang dapat ditinjau serta dilanjutkan kembali secara mandiri.

• ketika implementasi selesai
• ketika deploy dan verifikasi setelahnya selesai
• ketika hasil E2E dari perangkat nyata atau titik masuk pengguna sudah tersedia, atau ketika blocker sudah dipastikan
• ketika pekerjaan diserahkan karena interruption atau handoff

Pembaruan langsung bertujuan menjaga resume tetap aman, sedangkan phase checkpoint digunakan untuk meninjau dan mengembalikan sekumpulan perubahan. Memperlakukan keduanya dengan aturan yang sama telah memperbanyak micro-event commit.

Untuk pekerjaan tanpa wewenang commit, aturannya lebih sederhana. Selesainya review tidak mengubah status menjadi COMMITTED atau CLOSED. Kandidat integrasi tetap dalam keadaan freeze dan tidak dicatat sebagai penyelesaian durable sampai checkpoint yang sebenarnya tersedia.

Verifikasi worker disimpan di report dan dikeluarkan dari dokumen aggregate

Dalam pekerjaan paralel, setiap worker menghasilkan perintah yang dijalankan, hasil pemeriksaan, hunk yang bertumpang tindih, dan batasan yang tersisa. Menyalin semua itu kembali ke root TODO, README, dan requirements hanya menambah dokumen yang harus dibaca coordinator.

Bukti terperinci per worker disimpan di report yang immutable dan Git diff, sedangkan current-state hanya menyimpan kesimpulan terintegrasi, dampak saat ini, dan jalur bukti. Coordinator meninjau setiap report, tetapi tidak memperlakukan satu report sebagai satu commit. Beberapa report dalam phase yang sama dapat berbagi satu checkpoint setelah verifikasi terintegrasi.

Pemisahan ini membuat dokumen aggregate lebih ringkas tanpa menghilangkan verifikasi terperinci. Session berikutnya membaca status saat ini terlebih dahulu, lalu membuka report yang ditautkan dan Git evidence hanya ketika dasar penilaiannya diperlukan.

Urutan resume bertentangan dengan aturan owner

Setelah menata aturan, saya memeriksa kembali seluruh alurnya dan menemukan kontradiksi yang ternyata sangat mendasar. Prosedur awal mengharuskan README dibaca lebih dahulu, baru kemudian todo.md.

README menyatakan status yang mudah berubah tidak boleh diduplikasi, tetapi prosedur resume yang sebenarnya membaca router sebelum current-state. Jika kalimat status lama masih tertinggal, keputusan pertama pun bisa langsung bergerak ke arah yang salah.

Karena itu, saya mengubah urutan awal. Pertama-tama, canonical current-state digunakan untuk memeriksa Runtime saat ini, blocker, phase, dan tugas berikutnya. Setelah itu, README dan router dokumen digunakan untuk menemukan batas repository dan dokumen leaf yang diperlukan. Keputusan produk yang stabil dibaca dari current-direction, sedangkan kontrak perilaku yang sebenarnya dibaca dari requirements.

Menambahkan table owner saja belum cukup. Baik manusia maupun Agent harus mengikuti relasi kepemilikan itu dalam urutan baca yang sebenarnya.

Cakupan penerapan saat ini dan batasan yang masih ada

Struktur ini diterapkan pada aturan kerja bersama, routing dokumen Operations Automation, manifest dokumentasi perubahan, dan protocol coordination paralel. Skill validator, pemeriksaan sinkronisasi dokumentasi, dan pemeriksaan diff berhasil dilalui. Namun, perubahan saat ini masih berada di local working tree dan belum di-commit maupun di-deploy.

Saya juga tidak menulis ulang seluruh dokumen lama secara retroaktif. Riwayat dan report terperinci tetap dipertahankan; hanya ketika fakta current-state yang sama bertentangan di antara dokumen aktif, isinya dipangkas menjadi referensi ke owner. Daripada menghapus semua dokumen lama, lebih penting lebih dahulu mencegah dokumen itu kembali dibaca sebagai authority pekerjaan saat ini.

Sekarang, kualitas pembaruan dokumentasi tidak dinilai dari berapa banyak tempat yang diubah. Ukurannya adalah apakah setelah compaction atau handoff cukup membaca satu tempat tanpa salah memahami phase saat ini dan tugas berikutnya, sambil tetap dapat menelusuri bukti terperinci saat diperlukan.