Turn pending learnings into filed issues, and leave none pending that were handled. Triage files
issues only; it never edits a skill (skill-updater, /implement and /fleet do that).
reflect is ~/.claude/bin/reflect. Routing: skills/meta/reflect/references/routing.md. Issue
body, labels, dedupe and the -R repo flags: skills/meta/reflect/references/issue-format.md.
Steps
- Load.
reflect marker ls --json --status pending. Empty means say so and stop. - Infer. For a learning with no
skillor noscope, read itstext,before,afterand file, then match it to a repo skill (<repo>/.claude/skills/) or a library skill (reflect statusgives thelibrary:path). Resolve an installed copy to its library source asrouting.mddescribes. - Merge and drop. Merge pending learnings with the same skill and scope that say the same
thing (judged by reading
text,beforeandafter) into one item, keeping every example (file, line,before/after) and a count such as "seen in 4 places": the repetition is the evidence, and each merged learning still counts toward a proposal's 3+. Markrejectedonly a learning that an existing skill,AGENTS.md, rule or lint config already states. Check by reading the target; do not assume. - Propose. Show a table, one row per item: ids, text, count, route, reason. Wait for the user to accept, change or reject each row. Never file before this.
- File the accepted rows (below), then mark each.
- Propose upward (below) over the deferred and promoted learnings.
- Report the issue URLs, the proposals, and counts of promoted, deferred and rejected.
Routes
| Learning | Action | Mark |
|---|---|---|
| scope global, names a library skill | one issue on the skill's source repo | promoted |
| scope repo, names a repo skill | one issue on the learning's repo field (pass -R <owner>/<repo> from its origin) to amend that skill |
promoted |
kind later, scope repo |
inbox issue on that repo via file-issue inbox mode |
promoted |
scope repo with no skill (REFLECT(repo)), or no owner and no other learning shares its theme |
file nothing | deferred |
| user rejects, or a drop from step 3 | file nothing | rejected |
A merged item takes one route, and every learning in it gets that item's mark and --issue URL.
Group by skill: one issue per skill per run, listing every item for that skill. Use
the reflect issue format with labels reflect and status:ready, and add the from: line for
library issues. Put each item's count and every example's before/after under Evidence.
- Mechanical lessons (a script or linter could catch it): the issue also asks for a snippet in
the skill's
lint/folder, in the house forms (forbidigo, errorlint for Go). - Global issues always carry generic examples: rewrite each
before/after, and leave out repo names, paths and private identifiers, whether or not the library repo is public. - Repo issues on a public repo (
gh repo view <repo> --json isPrivate) are genericised too. An issue on the private repo the code came from keeps the code as written.
Proposals
After marking, run reflect marker ls --json and consider every learning with status deferred or
promoted and an empty proposal field. A learning already carrying a proposal URL belongs to a
filed group: skip it, so a group is never proposed twice.
| Group | Proposal |
|---|---|
3+ learnings in one repo on one theme, with an empty skill field and no repo skill in <repo>/.claude/skills/ covering it |
one issue on that repo suggesting a repo skill, an AGENTS.md line or an ADR |
| the same lesson in 2+ repos | one issue on the most likely library skill's source repo, with the from: line |
Judge "one theme" and "same lesson" by reading text, before and after; when unsure, leave the
learning out. Show the proposed groups to the user and wait for acceptance before filing, as in
step 4. A proposal lists each learning (id, text, repo, before/after) as evidence and stops
there: it contains no skill draft, no proposed wording and no patch. Use the reflect issue format
with label reflect, and the genericising rules above for global and public-repo issues.
After the proposal exists, for every learning in it, keep its status and record the URL:
reflect marker mark <id> <current-status> --proposal <proposal-url>
--proposal is separate from --issue, so a promoted learning keeps its own issue link.
Mark
After each issue is filed, for every learning in it:
reflect marker mark <id> promoted --issue <issue-url> [--scope global|repo] [--skill name]
reflect marker mark <id> deferred
reflect marker mark <id> rejected
Mark only after the issue exists, so a failed filing leaves the learning pending for the next run.
Pass --scope and --skill on any mark when step 2 inferred them. Re-running ls --status pending must show
nothing already handled.