readme_file.explain_code

Goal

• Read the Python files passed by the user and write explain_code.<descr>.md, documenting their classes, functions, interfaces, and relationships

Workflow

Read the Files

• Read every Python file <FILE> passed by the user or referenced in the request

Generate the Document

• Write the file in the current directory as explain_code.<descr>.md
  • <descr> is a short slug, typically the source file's basename without extension (e.g., batch_call_auction for batch_call_auction.py); use a combined slug for several files
• Say in the output file how it was generated, with this line right after the title:

  - Generated by `.claude/skills/readme_file.explain_code/SKILL.md`
  

• Include the five sections below, in this exact order
• Under each section, print one level-2 header (## ) per file read, using the same path used to read it (this disambiguates files with the same basename)
• Omit a section, or a file's subsection within it, entirely if there is nothing to report; never print an empty header or a placeholder bullet like -
• Print the result only to the file, not to the screen

Verify

• Follow the # Verification checklist below before returning the result

File Description

• Print a nested bullet list per file: its abstractions and functionalities

• Order files by use relationship

  • E.g., if file X is imported by Y, then X comes before Y in the list

• E.g.,

  - `batch_call_auction.py`
    - In-memory order book for a batch call auction
    - Queues buy/sell orders, buckets by capability tier
    - Clears each tier at a uniform price once per round
  - `passthrough_proxy.py`
    - LLM provider gateway
    - Routes a prompt to a registered provider
    - Times the call, estimates cost, and logs every request/response pair for
      later query
  

Class Description

• For each file, print one bullet per class, with a description under 20 words

• E.g.,

  # Class Description
  
  ## `research/Noesis/batch_call_auction.py`
  
  - `Bid`
    - Buyer order: (tasks, min tier, max latency, min reliability, max price)
  - `Ask`
    - Seller order: (tasks, tier, typical latency/reliability, min price)
  - `Fill`
    - One matched buyer/seller trade at a tier's uniform clearing price
  - `TierClearResult`
    - Outcome of clearing one tier (price, fills, unfilled quantities)
  - `OrderBookStore`
    - Abstract pluggable storage backend for pending bids/asks
  
  ## <file.py>
  ...