Reframe Module 9 worked-examples off already-built features (#40) (#70)

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>
This commit was merged in pull request #70.
This commit is contained in:
2026-06-22 17:51:57 -04:00
committed by Claude (agent)
parent f743bb671b
commit ba66f8a622
2 changed files with 46 additions and 35 deletions
+19 -14
View File
@@ -165,16 +165,17 @@ for both.
So how do you decide? A useful heuristic, which is really a property of the *issue*, not the model:
**Hand it to an agent when the issue is well-scoped, has concrete acceptance criteria, and follows
a pattern already in the codebase.** The `delete <index>` command is a strong candidate — it mirrors
the existing `done` command almost exactly, "done" is unambiguous, and a human can verify the result
in seconds. The bug above is another: contained, reproducible, testable.
a pattern already in the codebase.** An `undone <index>` command — the inverse of `done` — is a
strong candidate: it mirrors the existing command almost exactly, "clear the done flag" is
unambiguous, and a human can verify the result in seconds. The bug above is another: contained,
reproducible, testable.
**Keep it with a human when the issue carries genuine ambiguity, design judgment, or cross-cutting
risk.** "Add task priorities" sounds small but isn't: how many levels? Does the list re-sort? How are
priorities displayed and stored? Those are product decisions an agent will *answer confidently and
probably wrongly*, because nothing in the issue tells it the right call. A human resolves the
ambiguity first (often by splitting it into clear sub-issues — at which point the pieces may become
agent-ready).
risk.** "Add due dates" sounds small but isn't: what date format does the user type? Does the list
re-sort by date? How are overdue tasks shown, and in whose timezone? Those are product decisions an
agent will *answer confidently and probably wrongly*, because nothing in the issue tells it the
right call. A human resolves the ambiguity first (often by splitting it into clear sub-issues — at
which point the pieces may become agent-ready).
Notice the heuristic doesn't ask how smart the model is. It asks how well-specified the *work* is.
A vague issue degrades gracefully with a human — they ask you a question — and catastrophically with
@@ -244,13 +245,17 @@ from whichever forge's web form you happen to be filling in.
### Part A — Find the work
Look at the `tasks-app` and find three real pieces of work. You already know two from earlier
modules; the app is deliberately thin, so there's plenty. Good candidates:
Look at the `tasks-app` and find three real pieces of work. The app is deliberately thin, so there's
plenty it still can't do. Because it's carried forward across modules, skip anything you may have
already built (a `delete` command, task priorities) and pick work that's genuinely still missing.
Good candidates:
1. **A bug**`python cli.py done 99` (an out-of-range index) and `python cli.py done abc` (a
non-integer) both crash with an uncaught traceback. Run them and watch.
2. **A small, patterned feature** — a `delete <index>` command, mirroring the existing `done` command.
3. **A judgment-heavy feature** — task priorities (levels? sorting? display? storage?).
2. **A small, patterned feature** — an `undone <index>` command that clears a task's done flag,
mirroring the existing `done` command (it's the inverse).
3. **A judgment-heavy feature** — due dates on tasks (date format? sorting? overdue display?
storage?).
### Part B — Draft three well-formed issues
@@ -269,9 +274,9 @@ On your forge:
2. Apply a small label set to each: a **type** (`bug`/`feature`), a **priority**, and — for the ones
that qualify — a **`ready`** label meaning the acceptance criteria are solid enough to start.
3. **Route them.** This is the module's core exercise:
- Assign the **judgment-heavy feature (priorities) to a human** — yourself. It has unresolved
- Assign the **judgment-heavy feature (due dates) to a human** — yourself. It has unresolved
design questions; it is not agent-ready as written.
- Earmark the **bug** and the **`delete` feature for an agent.** They're well-scoped, patterned,
- Earmark the **bug** and the **`undone` feature for an agent.** They're well-scoped, patterned,
and easy to verify. Use whatever your forge offers: an actual agent assignee, an `agent-ready`
label, or just a note in the issue saying "suitable for an issue-to-PR agent (Module 25)." The
mechanism doesn't matter yet; the *decision* does.