document-code

# Code Documentation Assistant Build structured understanding of code entry points with an analysis-first workflow. ## Hard Rule - Do not create documentation until the entry point is validated and analysis is complete. ## Workflow 1. Gather & Validate - Confirm entry point (file, folder, function, API), purpose, and desired depth. - Verify it exists; resolve ambiguity or suggest alternatives if not found. - Search for existing knowledge before analyzing: `npx ai-devkit@latest memory search --query "<entry point name or purpose>"` 2. Collect Source Context - Summarize purpose, exports, key patterns. - Folders: list structure, highlight key modules. - Functions/APIs: capture signature, parameters, return values, error handling. 3. Analyze Dependencies - Build dependency view up to depth 3, track visited nodes to avoid loops. - Categorize: imports, function calls, services, external packages. - Exclude external systems or generated code. 4. Synthesize - Overview (purpose, language, high-level behavior). - Core logic, execution flow, patterns. - Error handling, performance, security considerations. - Improvements or risks discovered during analysis. 5. Create Documentation - Normalize name to kebab-case (`calculateTotalPrice` → `calculate-total-price`). - Create `docs/ai/implementation/knowledge-{name}.md` using the Output Template — this is the source of truth. - Include mermaid diagrams when they clarify flows or relationships. 6. Offer HTML Artifact - After the markdown is written, ask the user once: "Also generate an HTML artifact for easier scanning? (y/N)". - If yes, generate sibling `docs/ai/implementation/knowledge-{name}.html` per the HTML Artifact spec. Regenerate from the markdown on subsequent runs; never hand-edit. - If no or no response, stop here — markdown alone is a complete result. ## HTML Artifact Generated only when the user opts in at step 6. A self-contained HTML file optimized for scanning, not reference reading. Complements the markdown — does not replace it. Constraints: - Single file. Inline CSS. No build step. Only external asset allowed is mermaid via CDN (`https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js`). - Card-based grid layout, not a long scroll. The reader should capture structure at a glance. - Responsive down to laptop width. Print-friendly. - No interactivity beyond collapsible deep-dives and mermaid pan/zoom. Section mapping (from the Output Template): - Overview → hero card: title, one-line purpose, language/type badges. - Implementation Details → grid of sectioned cards with short bullets, not prose. - Dependencies → graph card (mermaid) plus a categorized list (imports, calls, services, external). - Visual Diagrams → full-width rendered mermaid blocks. - Additional Insights → callout boxes, color-coded by kind (info, warning, risk). - Next Steps → checklist card. - Metadata → compact footer (date, depth, files touched). ## Red Flags and Rationalizations | Rationalization | Why It's Wrong | Do Instead | |---|---|---| | "I already understand this code" | Understanding ≠ documented understanding | Write it down, then verify | | "The code is self-documenting" | Future readers lack your current context | Capture the why, not just the what | | "Dependencies are obvious" | Implicit dependencies cause surprises | Map them explicitly to depth 3 | ## Validation - Documentation covers all Output Template sections. - If an HTML artifact was generated, it opens standalone in a browser, renders mermaid, and reflects the markdown content (no drift). - Summarize key insights, open questions, and related areas for deeper dives. - Confirm file path(s) and remind to commit. ## Output Template - Overview - Implementation Details - Dependencies - Visual Diagrams (mermaid) - Additional Insights - Metadata (date, depth, files touched) - Next Steps