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

FileKindSize
SKILL.mdskill md6.4 KB
---
description: Document a Python file's classes, functions, and relationships in markdown
model: sonnet
---

# 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:
  ```markdown
  - 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.,
  ```markdown
  - `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.,
  ```markdown
  # 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.,
  ```markdown
  # 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.,
  ```markdown
  # 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.,
  ```markdown
  # 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.,
  ```markdown
  # 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: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated 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: 322kUpdated 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: 322kUpdated Claude CodeCodexVerifiedInstall