/reflect

name: cq:reflect
description: Mine the current session for knowledge worth sharing — identify learnings, present them for approval, and propose each approved candidate to the cq knowledge store.

/cq:reflect

Retrospectively mine this session for shareable knowledge units and submit approved candidates to cq.

Instructions

Step 1 — Summarize the session context

Construct a compact session summary covering:

• External APIs, libraries, or frameworks used.
• Errors encountered and how each was resolved.
• Workarounds applied for known or unexpected issues.
• Configuration decisions that only work under specific conditions.
• Tool calls that failed before the correct approach was found.
• Any behavior observed that differed from documentation or expectation.
• Dead ends abandoned and why.

The summary should be dense prose — enough for a reader with no prior context to reconstruct the session's technical events. Omit routine file edits, standard library calls, and anything already well-documented.

Step 2 — Identify candidate knowledge units

Reflection is agent-led — there is no MCP tool for this step. Using your own reasoning, scan the session for insights worth sharing.

A candidate is worth sharing if it meets **all** of these criteria:

1. **Generalizable** — applies beyond this specific project or codebase. Strip all organization-specific names, internal service names, and proprietary identifiers. 2. **Non-obvious** — not directly stated in official documentation, or contradicts documentation. 3. **Actionable** — another agent could apply it immediately with a concrete change. 4. **Novel** — unlikely to already exist in the commons (err toward including, not excluding).

Look specifically for:

• **Undocumented API behavior** — an endpoint returned an unexpected status code, response shape, or side effect.
• **Workarounds for known issues** — a library or tool required a non-standard setup to function correctly.
• **Condition-specific configuration** — a setting, flag, or option that behaves differently across versions, environments, or operating systems.
• **Multi-attempt error resolution** — an error that required more than one failed fix, where the solution was not obvious from the error message or documentation.
• **Version incompatibilities** — two libraries, tools, or runtimes that conflict at specific version combinations.
• **Novel patterns** — a non-obvious approach that solved a class of problem elegantly.

Do **not** include:

• Standard usage of a well-documented API.
• Project-specific business logic or implementation details that cannot be generalized.
• Insights already surfaced and confirmed during the session (i.e. knowledge units you retrieved via `query` and subsequently called `confirm` on to record that they proved correct).
• Insights you already proposed via `propose` during this session.

For each candidate, assign:

• **summary** — one concise sentence describing what was discovered.
• **detail** — two to four sentences explaining the context and why this behavior exists or matters.
• **action** — a concrete instruction on what to do (start with an imperative verb).
• **domains** — two to five lowercase domain tags (e.g. `["api", "stripe", "rate-limiting"]`).
• Optionally: **languages**, **frameworks**, **pattern** if relevant.

These are soft targets; the schema also enforces hard ceilings — 500 characters for `summary`, 8000 for `detail`, 2000 for `action` — and an over-limit candidate is rejected, never truncated.

For each candidate that resolved an error that occurred earlier in this session (i.e. a tool call or action failed before the successful resolution was found), mark it with ⏱ in the Step 3 presentation. Record the count of ⏱ candidates in the Step 6 summary — these represent missed mid-task propose calls and make the protocol gap visible to the user.

If the session contained no events meeting the above criteria, skip Steps 3–5 and follow the "no candidates" instruction in Step 6.

Step 2.5 — Run the VIBE√ safety check on each candidate

Apply the VIBE√ safety check (V — Vulnerabilities, I — Impact, B — Biases, E — Edge cases; defined in full in the cq skill) against every candidate from Step 2. Classify each finding as clean, soft-concern, or hard-finding. For hard findings, generate the sanitized rewrite covering every `propose` field that could carry the violating content (`summary`, `detail`, `action`, `domains`, `languages`, `frameworks`, `pattern`). Record the classification per candidate — Steps 3 and 6 use these results for presentation and the final summary.

If a hard finding cannot be coherently sanitized, the candidate fails Step 2's generalizable criterion — drop it from the candidate list and record the exclusion in Step 6's summary. Do not present it. `/cq:reflect` never silently drops *presented* candidates; the user owns the final decision on every candidate that reaches Step 3.

Step 3 — Present candidates to the user

Open with:

cq identified {total} potential learning candidates from this session...

{hard} have hard concerns and are shown with both the original and a sanitized rewrite — pick which (if either) to store.
{soft} have soft concerns flagged with ⚠️ for your awareness.
{clean} passed the VIBE√ check cleanly.

Omit any count line whose value is zero.

Present each candidate as a numbered entry. Use one of three templates depending on what Step 2.5 produced. Every template has a blank line after the `{N}. {summary}` header so the metadata block is visually distinct.

For any candidate marked with ⏱ in Step 2, prepend the line `⏱ Resolved an earlier-session error (missed mid-task propose).` as the first line of the metadata block. When both `⏱` and `⚠️` apply, `⏱` comes first.

**Clean candidate:**

{N}. {summary}

   Domains: {domain tags}
   ---
   {detail}
   Action: {action}

**Soft-concern candidate** (add the `⚠️` line as the first line of the metadata block, above