Churn-Gated Doc Drafting: Let the Model Write Only Sections Whose API Surface Has Settled

说明与用途

实现一个 CI 门控，允许模型仅自动撰写 API 表面稳定且提交变动低的文档章节，关键章节保持人工所有。

问题

Decide which documentation sections a model can draft based on API stability and commit churn, avoiding risky automated prose.

结果

The workflow enables automated drafting of low-risk documentation sections while keeping critical, high-risk content under human control, reducing manual effort and preventing drift.

工作流

• Write a human-owned anchor map linking each doc section to its API symbol and file, marking ownership status.
• Fingerprint the exported API surface by filtering go doc -all output and hashing declaration lines.
• Measure commit churn over a fixed window (e.g., 180 days) for each source file.
• Apply a drafting rights table that maps churn and fingerprint changes to allowed model output.
• Enforce the contract in CI by refusing drafts that violate the gate, emitting NEEDS_HUMAN lines for missing facts.
• Fail the build if a drafted section’s surface fingerprint has changed or churn exceeds thresholds.
• Review and update human_notes in the anchor map based on NEEDS_HUMAN responses.
• Iterate the process as the codebase evolves.

证据

A model should draft a documentation section only when the exported surface that section describes has stopped moving, and every other section should stay human-owned with an explicit anchor.

来源

Churn is a count of commits touching the defining file inside a rolling window, and it is deliberately cheap to compute.

来源

Four categories stay human-owned no matter what the numbers say: error message meaning, permission and security boundaries, deprecation promises, and numeric limits.

来源