Appearance
Find-todos
A backlog builder, and the one skill-smith build that outgrew its corpus and became its own installer part. It sweeps the whole project for todo: and maybe: markers and hands finn one prioritised file, TODOS.md, grouped by system and sorted by priority, with a couple of lines in his own voice on what each marker is really flagging and the move to make. The sweep fans cheap scouts out over the project in parallel and runs a mechanical grep net alongside them as the ground truth, so a forgetful scout can never shrink the result. A second command renders the finished backlog into a self-contained, chalk-themed html page.
In Practice
The sweep is a fan-out with a safety net – one todo-scout per slice of the tree, a single grep pass over the whole tree as the ground truth, then a collate step that folds in any line the scouts missed.
Sweep the project for markers. You want the outstanding work collected, so you run:
/find-todosIt slices the project into chunks a scout can hold – top level dirs, a big dir split further – skips the noise (.git, node_modules, dist, build, target, archive, binaries), then spawns one haiku todo-scout per slice in parallel. Each scout greps its slice for the four markers, reads a couple of lines around every hit, and returns a flat list of { file, line, marker, text, system_guess, note }. Alongside them one grep net sweeps the whole tree with (?i)\b(todo|maybe)\s*:, and any line it caught that no scout returned gets folded in at collate time. That is the scout-finds, skill-reasons split: a cheap fast finder fanned out per slice, and one reasoning orchestrator – the skill itself – that classifies each hit to a system, ranks it by the rubric, and writes a couple of lines in finn's voice per entry.
The result is TODOS.md at the project root, a snapshot header on top and one section per system:
# TODOS, project backlog
swept YYYY-MM-DD, a snapshot, the code is the truth, re-run /find-todos to refresh
N todos, N maybes, N highEach entry carries a bracketed priority tag, the trimmed marker line, and the blurb:
- [MED] `todo:` src/render/sprite.cpp:88 – todo: batch these draw calls
the sprite path submits one draw per sprite, this is the batching youve been meaning to do, real perf win once the renderer settles, medium not high bc nothings on fire yetThe sweep is on demand only – it never rides a hook, because a full fan-out costs, and staleness is just the date in the header, not something to chase.
Render the backlog to a page. With a TODOS.md in hand you turn it into something readable:
/find-todos-htmlThat runs render-todos.nu, which drives marked over the markdown through npx and drops a single scrolling html page beside the doc, in the same dark green theme as chalk. The bracketed tags the skill wrote survive the markdown pass as literal text, so the render swaps each one for a coloured pill – red for [HIGH], amber for [MED], green for [LOW]. If there is no backlog yet it stops and tells you to run /find-todos first; if npx is not on the path it prints npx not on path, install node first rather than half rendering.
An example outcome. One command later you have a triage-ready backlog you can read top to bottom – a draw-call-batching todo: sits near the top of its section in amber, a speculative maybe: sits at the bottom in green, and nothing got lost because the grep net backstopped every scout.
The Priority Rubric
Every hit lands in one of three tiers, and the rubric is spelled out so two sweeps of an unchanged tree rank the same way.
| Tier | Tag | What earns it |
|---|---|---|
| high | [HIGH] | A correctness, safety, data loss, or security concern, something that blocks active or shipping work, or a marker whose own text says before release, before ship, before merge, or fix. |
| medium | [MED] | A real improvement to a system in active development – maintainability, tech debt with teeth. The default for a bare todo:. |
| low | [LOW] | Cosmetic, speculative, or nice to have. The default for a bare maybe:. |
Two tie-breaks settle the rest: a todo: outranks a maybe: at the same signal level, since a maybe is speculative by nature, and a marker with no surrounding context falls to its marker's default – todo medium, maybe low. Inside TODOS.md the systems are ordered by their heaviest hit, so a system holding a high sorts above one that is all low. Only todo: and maybe: are in scope – FIXME, HACK, and XXX never enter the match set, on either the scouts or the grep net.
The Grep Net
The scouts are cheap haiku agents, and a cheap agent can forget a line. The grep net is the answer – one mechanical sweep of the whole tree, run alongside the scouts, is treated as the ground truth for which lines actually match. At collate time every line the net found is checked against what the scouts returned, and any line a scout dropped is folded back in with a system guessed from its path and a blurb from a direct read. The consequence is a one-way guarantee: a scout can only ever add context to a line, never remove it from the result, so a forgetful or erroring scout can never shrink the backlog. If a scout returns junk or falls over entirely, the net still carries its lines and the sweep completes.
Out of the Corpus
find-todos started as a banked build inside skill-smith's few-shot corpus, one of six installer parts that used to source their files straight out of references/built/. It moved out whole on 2026-07-30, into harness/modules/skills/find-todos/, on the plain argument that a part's source material has no business living inside another module's few-shot corpus. What surfaced the coupling was a proposal to retire skill-smith to harness/retired/, which is out of the PARTS array and read only by rule, so all six parts would have been left reaching into a retired module. That retirement was not taken (skill-smith stayed a part and went global-only instead, which changes where it installs, not where its files are sourced from), but the decoupling was worth doing on its own merits. Five of the six still source from the corpus today – lesson-recall, finn-style-sweep, cpp-lua-bind, profiler-zones, natvis-writer – find-todos is the one that left outright, the one banked skill that graduated all the way out into its own part.
It also keeps a different shape from its new neighbours. It's the one bundle in the modules/skills/ bucket – a skill plus two commands plus an agent, copied as a nested skills/find-todos/ dir – where media-grab and task-anchor sit as bare skill dirs one level up. Its row still sits in skill-smith's INDEX.md as a few-shot example for future builds, but it now points a reader at this new home rather than at files that no longer live there.
Key Files
SKILL.md
The procedure – the seven step sweep: slice, fan out scouts, run the grep net, collate and dedup, classify and prioritise, blurb, write TODOS.md. It also fixes the match set – exactly four markers, case-insensitive, todo:, todo :, maybe:, maybe :, and nothing else, no @todo, FIXME, HACK, or XXX.
references/rubric.md
The reasoning half – loaded on demand before classifying. It holds the three-tier priority rubric, the grouping rule (by system, then priority), the blurb voice (finn's own casual lowercase, written to finn and not to an agent), and the exact TODOS.md layout down to the bracketed tag shape the html render keys on.
agents/todo-scout.md
The scout – a read-only haiku subagent with just Grep, Read, and Glob, spawned one per slice. It finds the four markers in a single grep pass, reads a couple of lines around each, guesses a system, and returns a json array of hits. It never edits, never ranks or blurbs, and never widens the marker set – it only finds and describes, the skill does the reasoning.
scripts/render-todos.nu
The renderer – a Nushell script that turns TODOS.md into one self-contained html page. It reuses chalk's marked pipeline and a trimmed copy of its dark green theme, then swaps the bracketed [HIGH] / [MED] / [LOW] tags for coloured pills. It fails loud and early: a missing backlog prints no backlog at ..., run /find-todos first, and a missing npx prints npx not on path, install node first.
commands/find-todos.md
The /find-todos entry – loads the skill and its rubric, runs the sweep, and writes TODOS.md at the project root with the headline counts. It tells the sweep never to silently cap: on a big project it reports how it sliced things rather than quietly skipping any.
commands/find-todos-html.md
The /find-todos-html entry – renders an existing TODOS.md (or a path you pass) through render-todos.nu. If there is no backlog yet it runs /find-todos first rather than rendering a missing file. Html only, there is no pdf path here.
Connects to
- Grew out of Skill-smith – banked in its corpus as a build before it graduated whole into its own installer part, and its
INDEX.mdrow still stands as a few-shot example pointing at this module. - Borrows its whole render path from chalk –
render-todos.nudrives the samemarkedpipeline and a trimmed copy of chalk's dark green theme, so the backlog page and a chalk lecture read as the same family. - Feeds the context layer –
TODOS.mdis a root-level snapshot in the mould of the codebase map, explicitly not a source of truth, so you verify it against the code before acting and re-run the sweep to refresh it rather than editing it by hand.