Skip to content

gpsaggese/helpers / .claude/skills/readme_file.explain_code

readme_file.explain_code

Verified

Document a Python file's classes, functions, and relationships in markdown

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>
    ...
    

Class Interface

  • For each file, print every class with the class it descends from (or (dataclass) if it has no explicit base) and a nested bullet per method with its full signature and a description under 20 words

  • If a class defines no custom methods (e.g., a plain dataclass with only an auto-generated constructor), say so instead of listing a signature

  • E.g.,

    # Class Interface
    
    ## `research/Noesis/batch_call_auction.py`
    
    - `Bid(dataclass)`
      - `__init__(self, buyer_id: str, n_tasks: int, c_level_min: str, l_max: float, r_min: float, p_max: float) -> None`
        - Validates and stores one buy order
    
    - `Fill(dataclass)`
      - Plain data holder, no custom methods
    
    - `OrderBookStore(abc.ABC)`
      - `add_bid(self, bid: Bid) -> None`
        - Queue a bid
      - `clear(self) -> None`
        - Abstract, drop every stored bid/ask
    
    ## <file.py>
    ...
    

Function Interface

  • For each file, list module-level functions only, i.e., those defined outside any class (methods are covered under Class Interface)

  • Include underscore-prefixed functions when they hold core logic; skip trivial one-line helpers

  • One line per function: full signature and a description under 20 words

  • E.g.,

    # Function Interface
    
    ## `research/Noesis/batch_call_auction.py`
    
    - `_match_orders_in_tier(c_level: str, bids: List[Bid], asks: List[Ask]) -> TierClearResult`
      - Matches one tier's bids/asks and computes uniform clearing price
    
    ## <file.py>
    ...
    

Function Relationship

  • For each function in # Function Interface, list its callers and callees, scoped to the files read

  • Skip trivial delegations already implied by # Class Relationships (e.g., a method that only forwards to a stored collaborator)

  • E.g.,

    # Function Relationship
    
    ## `research/Noesis/batch_call_auction.py`
    
    - `_match_orders_in_tier()`
      - **Called by**: `OrderBook.clear_round()`, once per capability tier
      - **Calls**: no other functions in this file
    
    ## <file.py>
    ...
    

Class Relationships

  • Print relationships among all classes read, grouped under level-2 headers

  • Typical groups: ## Inheritance, ## Composition, ## Uses, and ## Mirrors (schema correspondence with no code dependency). Include a group only if it applies, and list only classes where the relationship holds

  • E.g.,

    # Class Relationships
    
    ## Inheritance
    
    - `OrderBookStore`
      - `_InMemoryOrderBookStore` from `batch_call_auction.py`
      - `PostgresOrderBookStore` from `postgres_store.py`
    
    ## Composition
    
    - `OrderBook`
      - Holds one `OrderBookStore`
    
    ## Uses
    
    - `OrderBook.clear_round()` calls `_match_orders_in_tier()` per capability
      tier and returns `Dict[str, TierClearResult]`
    - `TierClearResult` aggregates `List[Fill]`
    
    ## Mirrors
    
    - `BidRequest` (API layer) <-> `Bid` (matching engine): same fields, no
      shared code
    

Conventions

  • Follow .claude/skills/markdown.rules.md and .claude/skills/text.rules.md for markdown and text formatting
  • Keep every bullet description under 20 words
  • Enclose class names, function names, and file paths in backticks

Constraints

  • Do not modify the Python files being read
  • Base every bullet strictly on what the code shows; do not invent classes, functions, or relationships that are not present
  • Never print an empty section header or a placeholder bullet (- with no text)

Verification

  • Every class and function name mentioned exists in a file that was read
  • Every file that was read appears as a level-2 header in each section where it has content, using the same path used to read it
  • No section or subsection is present with zero bullets under it
  • Every description is under 20 words
  • The output file says that it was generated by .claude/skills/readme_file.explain_code/SKILL.md
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall