agentleFS
0xrsydn0xrsydn/pstack-pi/skills/reflect/SKILL.md

reflect

Skill7 starsChanged 34 days agoMITView on GitHub

Spawn three parallel review subagents over the active transcript, surface learnings, and route each to a concrete edit on an existing skill. Use when the user says reflect.

181 other projects use a version of this, 52 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use poteto-help and make-bot-ui.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ianclearySkill

    poteto-help

    Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.

    Also in 14 projects that use this

  • eryzerzSkill

    make-bot-ui

    Use when building a custom UI (page, dashboard, buttons) that should wake a Grok Bot over a webhook, when the user must provide a webhook sender key, or when exposing that UI on Tailscale.

    Also in 19 projects that use this

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 171 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use one parallel pstack_task call with three tasks.

    line 37
  2. Very specific:

    Use one pstack_task call with agent: "general-purpose", role: "reflect-judgment-divergent-synthesizer", and readonly: false.

    line 49
  3. Very specific:

    Before applying any Accepted edit, present the synthesizer's full Accepted/Rejected/Backlog output to the user and wait for explicit …

    line 57
  4. Very specific:

    If your environment ships a SKILL.md validator, run it on every touched skill before declaring done.

    line 68

“Common” is measured: kept by at least 6 in 10 of the 171 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Reflect

Mine the current conversation for durable learnings, then route them into skill edits.

When to invoke

  • The user said "reflect" or "/reflect".
  • A complex task (5+ tool calls) just landed cleanly and the recipe is worth keeping.
  • The agent hit dead ends, found the working path, and the path generalizes.
  • The user corrected the agent's approach mid-task.
  • A non-trivial workflow emerged that isn't captured anywhere.

Skip when the conversation is trivial, off-topic, or already covered by an existing skill the parent followed correctly. One-offs are not learnings.

Process

1. Locate the active transcript

The parent finds its own transcript file before fanning out. The system prompt names the active workspace's agent-transcripts/ directory; use that path. Do not glob across ~/~/.pi/agent/sessions/*/. That crosses workspace boundaries and reads private chats from unrelated projects.

ls -t <agent-transcripts>/*.jsonl <agent-transcripts>/*/*.jsonl <agent-transcripts>/*/subagents/*.jsonl 2>/dev/null | head -10

Three transcript layouts: legacy flat (<id>.jsonl), current nested (<id>/<id>.jsonl), and subagent (<parent>/subagents/<child>.jsonl).

For each candidate, read the first JSONL line and check that message.content[0].text contains the conversation's opening user prompt. Take the matching path. If no path resolves, write a tight digest of the session and pass that instead.

2. Spawn three reviewers in parallel

Use one parallel pstack_task call with three tasks. Set agent: "general-purpose" and readonly: false. Reviewers need Model Context Protocol (MCP) access for context lookups. The prompt forbids file writes; the parent applies edits.

LensmodelPrompt template
Judgmentrole: "reflect-judgment-divergent-synthesizer"references/judgment-reviewer.md
Toolingrole: "reflect-tooling"references/tooling-reviewer.md
Divergentrole: "reflect-judgment-divergent-synthesizer"references/divergent-reviewer.md

Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers return findings in the subagent output.

3. Synthesize

Use one pstack_task call with agent: "general-purpose", role: "reflect-judgment-divergent-synthesizer", and readonly: false. The synthesizer can use MCP access to spot-check citations. Use references/synthesizer.md verbatim and insert each full review where marked.

4. Structural enforcement check

Sanity-check the synthesizer's Accepted list. For any item that would be enforced more reliably by a lint rule, script, metadata flag, or runtime check, move it from Accepted to Backlog. The synthesizer already applies this criterion; this is a final pass before edits land. See the encode-lessons-in-structure principle skill.

5. Apply

Before applying any Accepted edit, present the synthesizer's full Accepted/Rejected/Backlog output to the user and wait for explicit approval. The user picks which subset to apply and may redirect routings. Skill changes affect every future agent in the org; do not auto-apply.

Backlog items file to whatever devex / backlog tracker your team uses automatically. Those are tracker submissions, not skill edits. Only the Accepted list waits for approval.

For each approved Accepted item, follow the Routing field exactly:

  • Trivial existing-skill edit (a one-line bullet, a tightened sentence, a stale fact corrected): parent does directly.
  • Substantive existing-skill edit (a new section, a new pattern table, more than ~10 lines): author per the skill-authoring-style loop below skill and run its draft / test / iterate loop.
  • tune description: <skill path> (the skill exists but didn't trigger when it should have): author per the skill-authoring-style loop below and run its description-optimization loop.
  • new skill via skill-authoring: <kebab-name>: draft and iterate the skill directly. Do not invent the shape ad hoc.

If your environment ships a SKILL.md validator, run it on every touched skill before declaring done. Skip this step if it doesn't.

6. Summarize for the user

Short list, no preamble:

  • Edits applied: <skill path>. What changed, one line each.
  • New skills created: <skill path>. One line each (rare).
  • Backlog filed to the devex tracker: <issue title> (<tags>). One line each.
  • Dropped: one line per rejected finding + reason from the synthesizer.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.