@open-tomato/rafa 0.20.0 → 0.22.0

package/README.md

@@ -171,6 +171,44 @@ 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
@@ -289,24 +327,34 @@ from GitHub Issues:
   `rafa plan create --next` takes the first line that is neither done
   nor already being worked on, and stops rather than skipping ahead when
   that issue is not ready. `rafa plan create --issue=<n>` plans from one
-  issue directly.
+  issue directly. Epic lines on the roadmap are descended into when they
+  are open, `horizon:now` and not done, making their specs the walk's
+  focus; `rafa epics` shows one epic's specs as a table.
+- **Epics group specs into features.** An epic is a bigger issue with an
+  acceptance criteria, an estimate and an ordered checklist of its specs.
+  Specs carry the epic's label to join it, and rafa never plans across
+  two epics. Projects with no epics work exactly as before; an epic is
+  purely optional.
 - **A few labels carry the state**: `type:spec`, `spec:ready` (a person
   says a plan may be made from it), `spec:needs-work` (details pending,
-  or the planner's review found gaps and listed them), and `type:bug`
-  with `needs-triage` for what a run files on its own.
+  or the planner's review found gaps and listed them), `type:bug`
+  with `needs-triage` for what a run files on its own, `type:epic` and
+  `epic:<slug>` (the epic and its member specs).
 - **Safety, in short.** An issue's text ends up in an agent's prompt, so
   rafa plans only from an issue whose author can write to the
   repository, that a maintainer has labelled `spec:ready`, that is
   complete, and that holds no local path or token. Comments are never
   read into a plan, rafa never applies `spec:ready` by itself, and
   machine-specific failures a run meets stay off your public tracker.
+  Specs in an epic may not carry two `epic:` labels; `rafa issue ready`
+  refuses the second one.
 - **Other trackers.** GitHub Issues is what works today. Linear support
   is being ported from the project rafa grew out of, as an optional
   add-on in a later version. For anything else, open or upvote a request
   in [the issues](https://github.com/open-tomato/rafa/issues).
 
 The full guide, with the spec template explained, a prompt for drafting
-a spec and every gate in order, is
+a spec, epics and every gate in order, is
 [docs/specs-and-roadmap.md](docs/specs-and-roadmap.md).
 
 ## From a checkout
@@ -429,7 +477,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

@@ -205,6 +205,26 @@ Prose that the loop injects into the context of **only the tasks of one stage**:
 
 One `rafa:stage-context` block per stage (optional). The block binds to the nearest `# Stage:` heading above it whether it sits before that stage's tasks or after them, so place it straight after the heading, where a reader looks for it. When one stage holds two, the first is read and each later one is reported as `duplicate-block`. A block above every `# Stage:` heading belongs to no stage: the parser reports it as `orphan-stage-context` and does not read it.
 
+#### The documentation writer's section
+
+A spec may end with `## For the documentation writer`: the use cases,
+edge cases, config examples, analogies and rejected alternatives from its
+design session. Carry it into the plan as context for documentation tasks
+only, so it shapes the examples those tasks write: which situations they
+show and in what order, which config examples they give, lightest first,
+and which analogies they keep.
+
+* Put it in the `rafa:stage-context` of the stage holding the plan's
+  documentation tasks, the ones declared `{agent=doc-updater}`, trimmed
+  to what those tasks document. Never put it in `rafa:context`, which
+  reaches every task.
+* It never becomes tasks of its own. The plan's tasks come from the
+  spec's "Tasks the plan must carry"; a use case or example listed in the
+  section is material for a documentation task, not a deliverable.
+* When no stage holds such a task, because every documentation edit
+  folds into the task whose change it documents, the section stays out
+  of the plan. The spec keeps it for whoever documents the change later.
+
 ### `rafa:report` (agent output only)
 
 Agents return a structured report block at the end of their output. The loop parses this to record findings, blockers, and other metadata.