@open-tomato/rafa 0.19.0 → 0.21.0

package/README.md

@@ -171,11 +171,49 @@ the next one, so you rarely have to remember it.
 
    Then step 2 again, or `rafa plan create --next`.
 
+### Tracking effort and learning from skills
+
+Each run records what it cost in time, tokens and work, and which skills
+were offered, invoked and worked. Two commands read that record:
+
+```bash
+rafa effort collect        # gather and store session logs
+rafa effort report         # per-plan summary: sessions, tasks, costs
+```
+
+`rafa effort report` shows the per-plan tables (sessions by status and
+outcome), the task report tallies, and any runs whose preflight halted. To
+see which skills earned their place and which are ignored:
+
+```bash
+rafa effort report --skills
+rafa effort report --skills --plan=rafa-24-know-which-skills-earn
+```
+
+With `--skills`, the report shows per plan and per resolver (the method
+that picked which skills to offer: `planner` by task declaration, `tag`
+by ranking, or `none`):
+
+- Each **skill**: offered count, invoked count, reported in the outcome,
+  recurrence count, and its **signal**: `earning` (worked with no failure
+  recurrence), `recurring` (invoked but a failure recurred), `unmeasured`
+  (invoked with no failure strings declared), or `ignored` (offered but
+  never invoked).
+- Each **lesson**: injected count, recurrence count, and whether it
+  recurred.
+- **M1** and **M2**: how many task lines used skills you offered, and how
+  many of the skills you offered were actually invoked.
+- **Plan CI**: the settled result of the pull request's checks when it landed.
+
+The report opens with a fixed line explaining that it shows co-occurrence,
+not causation: a skill can be invoked and its failure recur for reasons the
+skill does not cover.
+
 ### Which agents and skills are involved
 
 A task line may end with a declaration, for example
-`{agent=tdd-guide effort=medium}`. The planner writes it; you can change
-it.
+`{agent=tdd-guide skills=dev-planner effort=medium}`. The planner
+writes it; you can change it.
 
 - `agent=` routes the task to a Claude Code subagent. The planner picks
   by the task's SHAPE: implementation, tests, prose, a red build, a
@@ -196,8 +234,8 @@ it.
   while the project or a loaded user tier holds a different copy, and a
   `project` pin while a loaded user tier does; pin the tier the refusal
   names, or delete or rename the copy it names. `loop start` refuses a
-  plan that names an agent it cannot resolve before any session is paid
-  for.
+  plan that names an agent or a skill it cannot resolve before any
+  session is paid for.
 - User-tier items are invisible unless `loop.settingSources` includes
   `user`. `rafa agent list` shows what a run sees, `rafa agent vendor
   <name>` copies one in or updates it, and `rafa skill check .claude/skills
@@ -205,6 +243,25 @@ it.
   not resolve, a missing field) before it costs a task.
 - The plan format itself is a skill, `dev-planner`, shipped in the rafa
   tier and used when the project has none of its own.
+- **Skills for this task.** A task may declare the skills it needs with
+  `skills=skill1,skill2` on its line. At dispatch, one of three resolvers
+  picks which skills to offer: `planner` uses the task's `skills=`
+  declaration exactly, in order; `tag` ignores `skills=` and ranks every
+  enabled skill against the task text to find the top 3 scoring above a
+  floor of zero; `none` offers no skills. The resolver is set by
+  `task.skills` in `.rafa/config.yaml` (defaulting to `planner`), and the
+  `--skills-resolver=` flag overrides it. A compact skill index is listed
+  in the planner's prompt so the planner sees what skills are available
+  before writing the task. When a task is dispatched, the prompt gains a
+  "Skills for this task" section with the skills the resolver picked, or
+  stays unchanged if none were picked. The dispatch record stores the
+  resolver name and which skills were offered.
+- **Lessons from earlier tasks.** Up to 5 lessons from the learning store
+  are added to a task's prompt as a "Lessons from earlier tasks" section
+  when `task.lessons` is `on` (the default). The lessons are blessed
+  passages from earlier task findings that recurred or reached a
+  confidence floor. When neither skills nor lessons appear, the prompt
+  stays unchanged from before.
 - `model=`, `effort=`, `tools=` and `budget=` on a task line set the
   session's model, reasoning effort, tool list and spending cap when no
   agent decides them.
@@ -410,7 +467,7 @@ and a line here is ticked by the change that finishes the feature.
   changed since you last looked
 - ✅ The right skills reach the right task, chosen when the plan is
   written
-- ⬜ Know which skills earn their place and which are ignored
+- ✅ Know which skills earn their place and which are ignored
 - ✅ rafa learns from its own runs: what one task works out is handed
   to the tasks that need it later
 - ⬜ Skills and lessons shared across projects and machines

package/dist/bundled/skills/dev-planner/SKILL.md

@@ -360,12 +360,19 @@ The recognised keys are the `DECLARATION_KEYS` of `src/utils/declaration.ts`, wh
 
 ### `skills=` declaration
 
+When a task needs help from a skill, name those skills with `skills=`. Skill names must come from the skill index provided in this prompt; naming a skill no tier holds is recorded as an issue. Names are comma-separated with no spaces.
+
 `skills` is a recognised key that maps to no flag: there is no CLI flag for a skill, so the names are parsed, kept on the dispatch record and stripped from the task text with the rest of the block. It stands on its own — `{skills=bun-testing}` is a declaration with no other key beside it — and a value that is not a comma-separated list of skill names is recorded as an issue rather than passed on.
 
+A task with no `skills=` declaration is valid — naming none is the answer when no skill guides the task.
+
 ```markdown
   - [ ] Port vitest tests to bun:test  {agent=build-error-resolver skills=bun-testing,vitest-migration}
+  - [ ] Add the Zod schema for `CreateJobRequest` with its unit tests
 ```
 
+The second example above has no `skills=` and is still a valid task declaration.
+
 ---
 
 ## Task sizing (session economics)