document-service

1# Document Service
2 
3Analyze codebases to produce structured technical documentation and architecture diagrams with source-of-truth citations. Every finding links back to the exact file and line it was derived from. Optimized for AWS workloads but works with any codebase.
4 
5## Core Principles
6 
7- **Explain WHY, not just WHAT.** The reader inherited this codebase and has zero context. Listing components is not enough — explain why the architecture is shaped this way. Search for code comments, TODOs, and commit messages that reveal design rationale. When no rationale exists, mark it `[RATIONALE UNKNOWN]`.
8- **Trace end-to-end flows.** For every API endpoint or message handler, trace the complete request path from entry to response. Note every intermediate step, transformation, timeout, and failure point. This is the "if it breaks at 3am, where do I look?" analysis.
9- **Deep-dive complex logic.** Identify the most complex or domain-specific code paths (ML pipelines, business rule engines, state machines, custom algorithms). Document HOW they work at the implementation level — the algorithm, key parameters, edge cases, and where production bugs will occur. Surface-level summaries of complex code provide no value over a naive AI prompt.
10- **Surface implicit knowledge.** Look for hardcoded values, magic numbers, environment-dependent behavior, and undocumented assumptions. These are the tribal knowledge items that disappear when teams leave.
11…