Skip to content

renzrollon/shippable-skills / skills/productivity/session-retro

session-retro

Verified

Retro the current session. Score it against session shapes, flag token waste with next-turn fixes, and propose wire-ins into the skills this conversation actually called.

references/skill-candidate-brief.md

View on GitHub
# Skill Candidate Brief: Author Contract

A durable handoff from a retro into a skill-author agent. It captures evidence
that a repeatable session procedure should become a new `SKILL.md`, without
writing the skill itself.

**Path:** `<handoff-dir>/skill-candidate-<slug>-<YYYYMMDD-HHMMSS>.md`

`<handoff-dir>` is a path the user passed or named in the request, else a `shippable-handoff-dir: <path>`
line in the instruction file (the first existing of `AGENTS.md`, `CLAUDE.md`,
`.github/copilot-instructions.md`; ignored when absolute or containing `..`), else the first existing of `.claude/handoff/`,
`.agents/handoff/`, `docs/handoff/`, else `.agents/handoff/` created. Slug = the proposed skill name in kebab-case.

**When to write**

- The retro finds a repeatable procedure not covered by an existing skill.
- Cap at the top 3 candidates per review. Skip one-offs, pure chat, and
  duplicates of existing skills (suggest extending those instead).

**Bound the brief** (~1-3k tokens): cite the concrete moments and the tool
pattern; treat the procedure steps as hypotheses the author must refine.

---

## Template (stable: skill-author agents depend on these headings)

```markdown
# Skill Candidate Brief: <slug>

## Meta
- source: interactive | loop
- slug: <kebab-case proposed skill name>
- confidence: high | med | low
- created: <ISO-8601 timestamp>
- session_refs: <e.g. this session, 2026-08-21>
- evidence_basis: current-session (live context, no transcript re-read)

## Proposed Skill
- name: <kebab-case>
- description: <what it does AND when to use it>
- when_to_use: <bullet list of user phrases / contexts>
- when_not_to_use: <bullet list: overlaps, one-offs, better existing skills>

## Evidence
<!-- The concrete moments this session, the tool pattern, the assigned shape + score.
     State clearly which steps below are inferred rather than directly observed. -->

## Procedure to Encode
<!-- Ordered steps a SKILL.md should teach. Hypotheses from what the session did: author must refine. -->
1. ...
2. ...

## Inputs / Outputs / Exit Criteria
- inputs: <args, flags, natural-language triggers>
- outputs: <files written, chat summary shape>
- exit_criteria:
  - [ ] ...

## Related Existing Skills
<!-- From the enumerated skill list. Name overlaps and why this is NOT a duplicate
     (or: "extend <skill> instead" and stop: do not invent a parallel skill). -->

## Open Questions
<!-- Gaps the author must resolve before writing SKILL.md (scope, tools, output path, etc.). -->

## Author Checklist
- [ ] Name + description are distinct from Related Existing Skills
- [ ] Trigger phrases are concrete enough to avoid under-triggering
- [ ] Procedure steps refined against at least one real session or user confirmation
- [ ] Inputs / outputs / exit criteria are testable
- [ ] Open questions resolved or explicitly deferred in the skill body
```

---

## Section rules

| Section | Rule |
|---------|------|
| **Meta.confidence** | `high` = a repeated procedural shape with durable domain knowledge; `med` = a single strong session; `low` = weak signal / thin evidence |
| **Evidence** | Cite the concrete moments. Never invent tool calls, quotes, or token counts. |
| **Procedure to Encode** | Hypotheses labeled as such. Prefer a locate → act → verify shape. |
| **Related Existing Skills** | Must check the enumerated skill list. Prefer "extend X" over a new skill when overlap is high. |
| **Author Checklist** | If unchecked blockers remain, say so when pointing the user at the brief. |

## Candidacy signals (what a retro looks for)

- The same multi-step procedure performed by hand that no skill covers
- A long, high-tool-count stretch reinventing a workflow absent from existing skills
- A mid/low shape score where a skill would have prevented the named failure mode
- A clear procedural shape (locate → transform → verify) with durable domain knowledge

**Skip:** one-off Targeted Fixes, chat-only stretches, and work already covered
by an existing skill (suggest extending that skill instead).

## Chat reply after write

Do **not** re-dump full briefs into chat. Reply with:

1. Paths to each `skill-candidate-*.md` written
2. A one-line summary per candidate (slug + confidence + why)
3. "Hand these to a skill-author agent to write the SKILL.md"

## Author consumption

A skill-author agent reads the brief, resolves the Open Questions with the
user, then writes `skills/<bucket>/<name>/SKILL.md` (and docs / manifest
wiring as needed). Prefer the brief's recommendations over re-deriving the
procedure; reopen the session only for gaps or contradictions.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall