Suggest edit — hard docs writer

Title

Name

Note

---
status: raw
tags:
- ai
- coding
- developer-tools
title: hard docs writer
type: idea
updated: 2026-04-11
visibility: public
---

# hard docs writer

a tool that automatically documents the confusing parts of a codebase, specifically optimized for making AI agents more effective. most codebases have sections that are genuinely hard to understand — complex state machines, subtle invariants, non-obvious initialization orders, implicit dependencies between modules. humans who built these parts hold the context in their heads; AI agents and new human engineers hit a wall.

the approach would be to identify these "hard" sections automatically (high coupling, low comment density, frequent bug origins, high churn), then generate detailed prose explanations that capture the intent and gotchas, not just what the code does mechanically. the target reader is an AI agent starting a new task — so the docs need to be dense, precise, and structured in a way that fits efficiently into a context window.

related: [[spec-driven-dev|spec-driven dev kit]], [[context-window-optimizer|context window optimizer]], [[agents-md-research|AGENTS.md research]], [[overnight-app-grinder|overnight app grinder]]