Skip to content

gpsaggese/helpers / .claude/skills/review.create_demo

review.create_demo

Verified

Goal

  • Given a dir that holds a tool, write code_demo.md in that dir
  • The file has four parts:
    • What the tool does, in a few lines
    • What to run: the command, its needs, its cost, and how long it takes
    • What is generated: each output file, what it holds, and the stage that writes it
    • What a past run gave, and how to check the output
  • Keep it short: a reader must run the demo after reading it for 5 mins
  • It is the source of the end-to-end demo in code_tour.md. The skill .claude/skills/review.create_code_tour/SKILL.md points to this file and does not repeat it

Conventions

  • Follow the template .claude/templates/review_create_demo.template.md
  • Follow .claude/skills/text.rules.md and .claude/skills/markdown.rules.md
  • Name each file in backticks, with its path from the repo root
  • Put each command in a fenced bash block, with > before the command
  • Take facts from the dir's README and from the files a run leaves. If a fact is not clear, write unknown and do not guess

Workflow

Get the Input

  • Take the dir from the arguments. If none is given, use the current dir
    • If the dir does not exist, report the error and stop
  • Write code_demo.md in the dir. The name is fixed, so it does not follow ## Generated File Naming of .claude/skills/skill.rules.md
    • If the file exists, read it, then overwrite it
  • Take the dir's README.md
    • If it does not exist, report the error and stop. Tell the user to run .claude/skills/readme_dir.create/SKILL.md on the dir first

Find the Demo

  • Find the runner: the executable that runs all stages, or the only executable
    • Take its path, flags, and example commands from the README of the dir and of the script
    • Check the flags with --help
  • Find the small example input: the smallest input file that the README or the tests use, e.g., paper_list.short.csv
    • Skim the whole file, so the text says what the rows are
  • Choose the output dir: take it from the README if it gives one. Else use ./run_demo, a dir in the current dir
  • Find the setup the command needs, e.g., PYTHONPATH, an API key, or Docker. Take it from the README of the dir
  • Find what the demo needs and costs
    • Name the needs: internet, an LLM, a browser, an API key
    • Say that the demo costs LLM calls when it calls an LLM
    • Do not run a command that costs money. Ask the user to run it
  • If the runner has --dry_run, run it. Check that it needs no internet, no LLM, and no browser

Find What Is Generated

  • Take the output file list from the README of the dir, e.g., from the section "Output Dir"
  • If the demo's output dir exists, list it and compare it with the README:
    > find <OUTPUT_DIR> -maxdepth 3 | sort
    
    • Keep only the files the demo makes
    • Open and add any file in the output dir that the README does not list
    • If a README file is missing from the output dir, say it is made only in some cases, and when
  • For each file or group, write:
    • The name, with <BASE> or NN as in the README
    • What it holds, in one short line. Open the file if the README is not clear
    • The stage that writes it
  • Cover the results, the issues, the summaries, and the cache and logs
  • If the output dir exists, take the past-run counts from the summary files
    • For each stage, take the items processed, completed, failed, and the issues
    • Take one or two values from a result file, e.g., a rating

Write the File

  • Fill the template in this order:
    • # What the Tool Does: purpose, input, and output, in 3 bullets
    • # Run the Demo: needs, cost, time, the command, and the dry run
    • # What Is Generated: the tree of the output dir, and the table of files
    • # Example Result: the past-run counts, one row per stage
    • # Check the Output: the checks a reader can fail
  • Use the table columns File, Written by, and Content
  • Write the example result only when an output dir exists
    • Say it is the result of a past run
    • Say the numbers can change with the internet and the LLM, but the files do not
  • In # Check the Output, write these checks when they apply:
    • Each summary file shows the counts of its stage
    • Each failed item is in the issues file of the same stage
    • A value of the report equals the value in one item's file
    • A second run of the same command skips the finished work
  • Do not add a diagram. The file is short text

Report

  • Print the file path, the demo command, what it needs, and what it costs
  • Print the list of files the demo makes
  • Do not commit the file

Constraints

  • Do not modify any file of the dir except code_demo.md. Delete the *.log files that a run created
  • Do not run a command that needs internet, an LLM, or a browser without the user
  • Do not invent a command, a flag, a file, or a number
  • Use : and not - to separate a file from its description
  • Do not use emojis or the em-dash

Examples

  • Run on the dir research/Estimate_academic_paper_quality
    • The runner is estimate_paper_quality.py, and the input is paper_list.short.csv
    • The command writes to ./run_demo. It needs internet, a browser for SSRN papers, and an LLM
    • One file per stage, e.g., 01-resolve.paper_list.json, and one summary per stage, e.g., 02-download.summary.txt
    • A past run: 5 of 5 papers resolved, 3 of 5 downloaded, and 3 papers rated

Verification

  • The output file is code_demo.md in the dir
  • The five template parts are present, in order
  • The command, flags, and input file exist, and the flags appear in --help
  • The file says what the demo needs, costs, and how long it takes
  • The paths in the file are from the repo root
  • Every file the demo makes is in the table, with its content and stage
  • The example result comes from a past run's summary files, and says so
  • The file has no diagram and no invented command
  • No line is over 85 characters outside code blocks and tables
  • No file of the dir changed, other than code_demo.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: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated 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: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall