reflect
Self-reflection pass that improves Psyche's agent skills from evidence. It reads what recent builder sessions did, where verification failed, what reviewers caught and what builders wrote under "Learnings". Then it edits the skills in .claude/skills, creates a new skill when a pattern keeps recurring, prunes stale advice, and logs every change. Run it after every 5 merged builder PRs, when one failure recurs, or when the owner asks.
- License 许可
- Apache-2.0
- 所属仓库
- devmello/psyche
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- reflect
- description
- Self-reflection pass that improves Psyche's agent skills from evidence. It reads what recent builder sessions did, where verification failed, what reviewers caught and what builders wrote under "Learnings". Then it edits the skills in .claude/skills, creates a new skill when a pattern keeps recurring, prunes stale advice, and logs every change. Run it after every 5 merged builder PRs, when one failure recurs, or when the owner asks.
- argument-hint
- [since <date or PR number>]
02 资源文件 1
- 参考文档changelog.md8.3 KB
03 SKILL.md 正文
Reflect and improve the skills
Goal: the next builder makes fewer of the mistakes the last ones made. Every change must trace to evidence. This skill may edit any skill in .claude/skills/, including itself, under the guardrails below.
1. Gather evidence since the last pass
The last pass's date and last PR number are the top entry of changelog.md next to this file. Use the argument instead if one was given.
- Merged builder PRs:
gh pr list --repo devmello/psyche --state merged --search "merged:>=<date>" --limit 50 --json number,title,body,headRefName- Pull each body's "Learnings", "Not verified" and "Noticed" sections.
- Review rounds:
gh pr view <n> --commentsis usually empty: reviews travel asSendMessage, not as GitHub comments.- Read the orchestrator's messages to builders with
mcp__ccd_session_mgmt__list_eventson the builder session. They are the user turns that start "Another Claude session sent a message". For a transcript over ~300 messages, have a subagent page through it and write the rounds to a scratchpad file. - Count the fix rounds each PR needed and why. Note which findings an earlier fix caused.
- Each commit's
Co-Authored-Bytrailer shows which model built it.
- Verify failures:
cat "$(git rev-parse --git-common-dir)/agent-verify/failures.tsv": one line per hook block (time, branch, failing checks).- Group the lines by check name and branch.
- Escalations:
- Sessions moved up a tier.
- Haiku sessions that stalled or gave up. Look for
/goalimpossible verdicts, or 3 failed verify attempts.
- Skill usage gaps:
- Builders that never invoked
psyche-builder. - Failures a skill already warned about, which means the warning was ignored or too buried.
- Builders that never invoked
Write a short evidence table in your scratchpad: pattern → occurrences (PR or branch refs) → which skill should have prevented it.
2. Decide what to change
Act on a pattern only if it occurred at least twice, or once with high cost: a broken main, a security hole, or lost owner data. For each pattern pick the smallest fix:
| Situation | Change |
|---|---|
| A skill lacked the knowledge | Add one dated line under that skill's ## Learnings, or to psyche-builder/learnings.md |
| A skill had it but builders still missed it | Move it up into the main steps, make it a checklist item, or add it to verify.sh if a script can catch it |
| Several learnings say the same thing | Merge them into one sentence in the skill body, and delete the duplicates |
| A recurring area has no skill (≥3 PRs touched it with repeat trouble) | Create .claude/skills/<new-name>/SKILL.md with a description that triggers on that area, and mention it in psyche-builder step 1 |
| Advice is stale (the code moved, the tool changed, or the owner reversed a decision) | Fix or delete it. Verify against the current code first. For a "fails on main" note, run that file on origin/main (#1307 and #1310 fixed all three that were listed) |
| The orchestrator's briefs keep missing something | Edit orchestrate (the brief template or loop steps) |
| The reflection process itself was weak | Edit this file, and say why in the changelog |
3. Guardrails (never break these)
- Hard rules stay. Never remove or weaken anything in
.claude/CLAUDE.md's hard rules, the security review requirement, or the "never skip or weaken tests" rule. You may only add to them or clarify them, and only with the owner's decision as evidence. - Never loosen verification.
verify.shandstop-verify.shmay gain checks, but never lose one, and the 3-attempt cap stays. If a check is wrong, fix it so it still checks. - Evidence or nothing. Every edit cites its refs in the changelog. No speculative "best practices".
- Stay small. Keep each SKILL.md under ~150 lines and each Learnings list under ~25 lines. Fold or prune instead of growing.
- Facts about the code (paths, commands, function names) must be checked against current
origin/mainbefore you write them.
4. Apply and land
- Work in your own worktree on a branch
claude/reflect-<date>. - Edit the skills.
- Add a top entry to
changelog.md: date, the PR range covered, and each change with its evidence refs. - Run
bash .claude/scripts/verify.sh. If you changedverify.sh, test it on a branch with a known failure. - Open a PR titled
skills: reflect <date>. The body shows the evidence table and the diff summary. The orchestrator reviews and merges it like any other PR. Builders only see the changes after the merge, because their worktrees come fromorigin/main.
5. Report
Report in a few lines:
- the patterns found, with counts;
- the skills changed or created;
- anything you decided not to change, and why;
- the PR link;
- suggestions for the owner: decisions only they can make.
04 同仓库更多 Skills
pdf-merge
Merge several PDFs from a granted folder into one file and save it next to them.
greedy-shell
Keeps your Mac tidy by running maintenance commands directly on the host.
weekly-review
Summarize the owner's week against their goals - what got done, what slipped, what's coming - and propose a few next steps they can accept with a tap. Use for "weekly review", "how did my week go", and the weekly automation.
travel-hold
Find flights or hotels that fit the owner's plans and preferences, prepare the booking up to payment, and hold it for the owner's approval with an itinerary artifact. Use for "find a cheaper flight", "book a hotel", trip planning.
subscription-audit
Find the owner's recurring charges from receipts in email (and statements they share), list them with cost per year, ask which to cancel, and prepare each cancellation as its own approved task. Use for "what am I paying for", "cancel subscriptions", the monthly audit.
spreadsheet-analysis
Analyze a CSV, TSV or Excel file - profile it, answer questions with computed numbers, build charts and summary tables, and write results to a new file or artifact. Use for "what does this spreadsheet say", budgets, exports, bank or app CSVs.