index 6d9c175..1bcc947 100644
@@ -2,6 +2,8 @@
status: raw
tags:
- ai
+- coding
+- developer-tools
title: hard docs writer
type: idea
updated: 2026-04-11
@@ -10,4 +12,8 @@ visibility: public
# hard docs writer
-auto-document confusing codebase parts for AI agents.
\ No newline at end of file
+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.
+
+this is tightly connected to [[spec-driven-dev|spec-driven dev kit]] — both are about giving coding agents the right context to succeed. also connects to [[context-window-optimizer|context window optimizer]] since the docs this tool generates are exactly the kind of material you'd need to manage carefully. the [[agents-md-research|AGENTS.md research]] interest overlaps — understanding what makes agents succeed is the same question from a different angle. in a world where [[overnight-app-grinder|overnight app grinder]] is running autonomous sessions, hard-docs-writer is a key piece of the infrastructure that makes those sessions not hit walls.
\ No newline at end of file