Goal

• You are an expert technical writer specializing in software documentation.
• Given a dir <DIR>, write its README.md following .claude/skills/readme_dir.rules.md and the template .claude/templates/readme_dir.template.md
• Say in the README how it was generated, with the line

  - Generated by `.claude/skills/readme_dir.create/SKILL.md`
  

• End the README with the section # Review roadmap: the map of the dir, how to run the tests, the reading speeds, and the table of files with the time to read each one
  • The skill .claude/skills/review.create_code_tour/SKILL.md reads this section to write the checklist that guides the review of the dir

Workflow

Examine the Directory

• List all subdirectories, files (Python/Markdown), and executables

Write the README

• Put the Generated by ... bullet from the Goal right after the title, before the Summary bullets

• Structure the README with the sections from .claude/skills/readme_dir.rules.md:

  • Summary, as bold-labeled bullets (Goal, Input, Output, Users)
  • Structure of the Dir
  • Description of Files
  • Description of Executables (if applicable)
  • Output Dir (if the executables write a tree of files in one dir), as a ## section of the executables, before the first executable
  • Description of Workflows (if applicable)
  • Description of Architecture (if applicable)
  • Review roadmap, as the last section, see "Write the Review Roadmap"

• Follow all formatting rules from .claude/skills/readme_dir.rules.md:

  • Description limits (e.g., <20 words for subdirs, 1-line for files)
  • Command formatting with > prefix and proper code blocks
  • Example ordering (simple to complex)
  • Table format for command references
  • Bullets only, no prose paragraphs, including the intro of each section
  • Many outputs as one sub-bullet per file or per group of files

Check the Commands

• Check each example command against the current CLI of its executable (e.g., with --help)
• Remove the args that the tool dropped, and rename the args that the tool renamed
• Check the commands in the workflows too

Take the Inventory

• List the tracked and untracked files of the dir, without ignored files:

  > git ls-files --cached --others --exclude-standard <DIR>
  

• Count the lines of every file with wc -l
• Mark the files with uncommitted changes:

  > git status --short <DIR>
  

• Skip these, and list them in the "Skipped" line with the reason:
  • Logs: *.log
  • Scratch files: tmp.*
  • Caches: __pycache__/, .ruff_cache/, .pytest_cache/
  • Symlinks
  • The checklist file code_tour.md
• Keep a raw export in the table, but give it no time
  • E.g., a CSV over 1000 lines that a person downloads
• Running the scripts of the dir can create <SCRIPT>.log files next to the scripts
  • Say it in the "Skipped" line, so that the reader ignores these files

Classify the Files

• Put each file in exactly one kind:
  • doc: README.md, *.README.md, files under docs/, log.md, todos.md
  • test: files under test/ or named test_*.py
  • code: all the other *.py and *.sh files
  • data: prompts, YAML, CSV, JSON, and other inputs read by the code
• Find the entry points
  • A file is an entry point if it is executable, or has _main and if __name__ == "__main__"
• Pair each code file with:
  • Its doc, e.g., <FILE>.README.md or the design doc that names it
  • Its test, e.g., test/test_<FILE>.py
• Find the test helpers, i.e., test files that have no test_ prefix, e.g., test/epq_test_utils.py

Set the Reading Time

• Use these speeds, in lines per min, and print them just above the table of the files:
  • Skim: 100, for any kind of file
  • Read doc and data: 30
  • Read code: 20
  • Read test: 40
• Compute the minutes of a file as ceil(lines / speed), with 1 as the minimum
  • The Mins column of the table uses the speed of the file's kind
• Sum the Mins of the table, and print the total in mins and in hours, rounded to the hour

Order the Code

• Build the import graph of the files of the dir
  • Read the import lines of each file, and keep the imports that point to another file of the dir
• Sort the code files bottom up
  • A file with no imports from the dir comes first
  • A file comes after all the files that it imports
  • Break ties with the smaller file first
  • Entry points come last, in the order that the docs give for running them
• If the graph has a cycle, report it in the line "Cycles in the import graph" and sort the files of the cycle by size

Find the Purpose of Each File

• For each file, read the docstring or the first lines, and the doc paired with it
• Write the purpose of a file in one short line
  • If the purpose is not clear from the file, write only the file name and put purpose unknown in the line
  • Do not guess

Write the Review Roadmap

• Write the section # Review roadmap as the last section of the README, following the template .claude/templates/readme_dir.template.md
  • If the section exists, write it again, and keep the ticked Read cells of the rows that are still in the new table
• Write the intro bullets
  • The use of the section
  • The path of the checklist file <DIR>/code_tour.md, made from this section by .claude/skills/review.create_code_tour/SKILL.md
• Write the map, as bullets, with the path from the repo root for every file
  • Purpose: one sentence, from the Goal of the Summary
  • Entry points, in run order, with one line each
  • Layers, bottom first, with one line each
  • Cycles in the import graph: none, or the list
• Write a subsection ## Testing
  • Take the way to run the tests from helpers_root/CLAUDE.md ## Testing
  • Give the command for the dev env and the command for Docker, in a fenced block
• Write a subsection ## Files and Reading Time, in this order:
  • The reading speeds and the total time to read every file once
  • A bullet that gives the order of the rows of the table
    • Say that the kinds come in the order code, doc, test, data
    • Say the order inside each kind: code bottom up and then the entry points, docs by number, tests in the order of the code that they test
    • Say that the order is not the order of the checklist, which mixes the kinds
  • The table with one row per file, including the data files
  • The Skipped line, the note on the <SCRIPT>.log files, and the other notes on the table, e.g., the code that has no test file of its own
• Make the table follow the template
  • Write the paths from the repo root in all the columns, so that the reader can open them directly
  • The first column Read holds [ ], to tick when the file is read
  • Put Mins next to Lines
  • Order the rows as the bullet above the table says
• The README is a row of the table
  • Write the section first, then set the Lines and Mins of the README row to the size of the final README, and update the total

Constraints

• Do not modify any file of <DIR>, other than README.md
  • Running the scripts of the dir can create *.log files: delete those that the run created
• Do not invent a command, a file, or a function
• Use : and not - to separate a file from its description
• Do not use emojis or the em-dash

Verification

• README.md exists in the target directory <DIR>
• The first bullet after the title is - Generated by `.claude/skills/readme_dir.create/SKILL.md`
• Every required section from .claude/skills/readme_dir.rules.md is present
• The Summary has the bullets Goal, Input, Output, and Users
• There is an "Output Dir" section if the executables write a tree of files
• There is no prose paragraph
• Description length limits and command formatting rules are followed
• Every example command, in the executables and in the workflows, uses args that the current CLI accepts
• # Review roadmap is the last section, with the subsections ## Testing and ## Files and Reading Time
• There is no # Map of the Dir header
• The table has one row per file of the inventory, or the file is in the "Skipped" line
• The table uses the path from the repo root for every file
• The reading speeds are printed above the table, and the Mins of each row follows them
• A bullet above the table gives the order of the rows, and the table follows it
• The Lines of the README.md row equals the line count of the final README
• No file of <DIR> changed, other than README.md