session-workflow-miner

Session Workflow Miner

Find repeated manual asks in recent Codex sessions and convert only the useful ones into durable, small operating artifacts.

Philosophy

Repeated asks are workflow telemetry. The useful response is not to create a bigger catalog; it is to identify the smallest durable owner for the repetition, prove that owner does not already exist, and create nothing when reuse is better.

When To Use

• Jamie asks what workflows or asks repeat across recent Codex sessions.
• Jamie asks which repeated tasks should become skills or custom subagents.
• A session review should focus on practical work such as CI failures, PR review, changelogs, docs updates, release prep, debugging, test triage, Linear state, or delivery-state drift.
• The desired output is a small set of concrete artifacts, not a broad process rewrite.

Inputs

• Lookback window, defaulting to recent sessions when Jamie does not specify one.
• Session collector root, usually ~/.agents/session-collector/.
• Target repo or workflow focus when provided.
• Existing skill and custom-agent inventories.
• Optional memory hits as routing hints, never as current-state proof.

Evidence Sources

Use the freshest available runtime evidence first:

1. ~/.agents/session-collector/ README and collector entrypoint.
2. A temporary collector output and bundle, usually under /tmp.
3. Existing skills under Skills/**, .codex/skills/**, and plugin skill roots.
4. Existing custom agents under the canonical Codex config source, commonly codex/agents/** in Jamie's configs checkout.
5. Memory only as a routing hint; verify current file state before claiming an artifact is missing.

Do not treat old session summaries, Slack messages, bot prose, or injected prompt bodies as source-of-truth evidence.

See references/contract.yaml for the compact contract and references/evals.yaml for smoke cases.

Workflow

1. Run or refresh the session collector into /tmp using a sandbox-safe cache path. Keep the live repo untouched unless the user explicitly asks for persistent reports.
2. Inspect the generated bundle first: aggregate.json, skillify-candidates.json, skill-refactor-handoffs.json, and any tool or attribution summaries.
3. Sample raw recent session prompts only when the bundle is too coarse. Filter out system/developer text, injected skill bodies, copied specs, hook prompts, and repeated heartbeat boilerplate unless the repeated heartbeat is itself the workflow under review.
4. Cluster repeated work by operational job, not by wording:
   • PR, CI, CodeRabbit, and mergeability triage.
   • Docs, changelog, release note, and publish handoff work.
   • Spec/plan review and acceptance-criteria hardening.
   • Test failure ownership and validation evidence.
   • Debugging, reproduction, and runtime-state investigation.
   • Linear, GitHub, and delivery-state synchronization.
   • Repeated human steering that should become a guardrail or validator.
5. Inventory existing skills and agents before creating anything. Prefer reuse or a narrow extension over duplicate artifacts.
6. Choose the durable form:
   • Create a skill when the repeated work is a reusable procedure with inputs, workflow, outputs, boundaries, and validation.
   • Create a custom subagent when the repeated work is a bounded role, especially read-only investigation, review, auditing, or state classification.
   • Recommend a validator or CI gate when the repetition is a correctness failure that deterministic checks can prevent.
   • Create nothing when an existing skill or agent already owns the job.
7. Create only the smallest useful artifact. Avoid broad routers, aspirational governance text, and placeholder scaffolding.
8. Validate the new artifact with the repo's narrowest available gate, then report what was created, what was deliberately skipped, and which evidence drove the decision.