run-summary

Run Summary

Overview

Retort runs produce small, single-task codebases (one REST API, one CLI, one service). Full codebase-summary treatment is overkill — but a consistent lightweight summary per run is exactly what makes cross-run comparison useful.

This skill is an intentionally scoped-down adaptation of pourpoise's codebase-summary. It runs in seconds, not minutes, and emits only what's useful when comparing 48+ small generated projects.

Parameters

• codebase_path (required): The run directory (same as evaluate-run's run_dir)
• output_dir (optional, default: {codebase_path}/summary): Where to write the summary files

Steps

1. Infer the surface

Read TASK.md to understand what the code is supposed to do — the "surface" of the project. One paragraph, no judgments.

2. Map the modules

Generate {output_dir}/modules.md:

# Modules

| Path | Purpose | Entry points |
|------|---------|--------------|
| src/app.py | HTTP server, route handlers | `app`, `create_app()` |
| src/models.py | SQLAlchemy models | `Book`, `Base` |
| src/db.py | Connection + migrations | `get_engine()` |
| tests/test_app.py | API integration tests | 8 test functions |

Constraints:

• You MUST list every non-generated source file (skip node_modules, target, __pycache__, .git, lock files, build artifacts).
• The "Purpose" column is one line extracted from the code, not invented.
• The "Entry points" column is the publicly-named functions, classes, or exported symbols — not every local helper.

3. Describe the interfaces

Generate {output_dir}/interfaces.md covering what the code exposes:

• HTTP routes (method, path, short description)
• CLI commands (subcommand + flags)
• Library API (exported classes/functions)
• Data schemas (tables, message formats)

Example:

# Interfaces

## HTTP routes

| Method | Path | Returns | Handler |
|--------|------|---------|---------|
| GET | /books | `[Book]` | `app.py:list_books` |
| POST | /books | `Book` | `app.py:create_book` |
| GET | /books/{id} | `Book \| 404` | `app.py:get_book` |

## Data schema

`books` table: id (int, pk), title (str), author (str), year (int).