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