Goal

• Analyze a Python file <FILE> passed by the user and generate or update <FILE>.README.md with documentation (Markdown using bullet points) about its architecture, code organization, idioms, and so on

Workflow

Read File

• Read the file <FILE> to understand its code structure:
  • Parse all function and class definitions
  • Identify the public API (exported functions, classes, constants)
  • Trace function call relationships (which functions call which)
  • Identify external dependencies (imports from other modules, libraries)
  • Note the module's purpose and role in the broader system

Check the Existing Readme

• Check if <FILE>.README.md already exists:

  • If it exists, read it and plan what to update
  • If it does not exist, plan content from scratch

• Make sure there is a note in the docstring of the corresponding files pointing to <FILE>.README.md, e.g.,

  For a description of the architecture of this file, see the file
  <FILE>.README.md
  

Generate Document

• Follow the template .claude/templates/architecture_doc.template.md

• Generate the documentation with these sections using markdown and bullet points following the rules in

  • .claude/skills/markdown.rules.md for markdown formatting
  • .claude/skills/text.rules.md for text formatting

Update Document

• Write the results to <FILE>.README.md in the same directory as <FILE>

• Wrap the text in 85 columns

Conventions

• Use conventions summarized in docs/documentation_meta/all.architecture_diagrams.explanation.md

• Use Mermaid diagrams (```mermaid) for all architecture diagrams

• The C4 notation with Mermaid should follow the standard C4 layout:

  • Person for external users
  • System for external systems
  • Container for application containers/processes
  • Component for internal components
  • Use Rel for relationships between elements

• Label diagrams clearly with what they represent

• Reference actual code artifacts (function names, class names, file paths) when available

• Distinguish facts from assumptions:

  • For facts (code-derived):
    • E.g., "The function process_data() calls validate_input() before computing results"
  • For assumptions:
    • E.g., "This likely handles error cases based on the try-except blocks present"

• Focus documentation on:

  • Maintainability: How easy is it to modify and extend this code?
  • Extensibility: How well does the design accommodate new features?
  • Operational understanding: What does someone need to know to work with this code?

Constraints

• Do not modify the original <FILE>
  • Only create/update <FILE>.README.md
• Do not over-document: avoid repeating what is obvious from the code
• Keep diagrams focused: one clear diagram is better than three cluttered ones
• Do not invent architecture that is not present in the code
• When uncertain about intent, mark the observation as an assumption
• Do not use emojis or decorative formatting

Verification

• <FILE>.README.md exists and documents <FILE>'s architecture
• The docstring in <FILE> references <FILE>.README.md
• Diagrams use Mermaid syntax with the C4 element types
• No architecture is invented that is not present in the code