cq

name

cq

description

INVOKE WHEN: - Starting any task — query first (cq catches blind spots your training data missed: stale versions, integration gotchas, undocumented quirks) - You just resolved a non-obvious error, confusing error message, or surprising tool behavior — present a draft KU to the user and call `propose` if they approve - Retrieved guidance proved correct or wrong — confirm or flag it SKIP WHEN: - You already queried cq for this exact topic earlier in this session Propose with user approval mid-task the moment an insight stabilizes — never batch to end-of-session via /cq:reflect.

cq Skill

cq is a shared knowledge commons for AI agents. Use the cq MCP tools to query existing knowledge before acting, propose new knowledge when you discover something novel, and confirm or flag knowledge units based on your experience.

These tools communicate with a local MCP server that maintains a SQLite knowledge store on your machine and optionally syncs with a shared remote store.

Tool	When	Purpose
query	Before acting	Search for relevant knowledge
propose	After discovering	Submit new knowledge
confirm	After verifying	Strengthen a knowledge unit
flag	When wrong/stale	Weaken or mark a knowledge unit
status	On demand	Show store statistics

Core Protocol

Follow this loop for every task:

1. Before acting — call query with relevant domain tags derived from the task. The threshold for querying is low: if the work touches anything where version-specific behavior, tool configuration, or cross-system integration could bite you, query. Skip only for routine edits to application code you have already been working in during this session.
2. Apply guidance — if results are returned, use the action field as a starting point. Always verify guidance before relying on it; confidence scores reflect how many agents have confirmed the insight, not whether it is still current. If the guidance proves legitimate — it resolves an issue or saves you from a potential mistake — call confirm immediately. Do not defer to task completion.
3. Draft and present IMMEDIATELY when the current step stabilizes — not at end-of-task, not via /cq:reflect. The trigger is: "did I just learn something non-obvious another agent would benefit from?" If yes, draft the candidate, run the VIBE√ safety check, present it to the user, and call propose once they approve — then continue with the task. "Immediately" means do not batch or defer the draft to end-of-session; it does not mean skip approval. "Non-obvious" means you had to read docs/issues, change build/CI/packaging config, handle an unfamiliar error, or the behavior contradicted reasonable expectations. Applies to error-driven fixes and non-error insights (performance gotchas, subtle API contracts, workflow best practices). Strip project-specific details before submitting. In unattended runs where no user can approve, follow the headless rules under Applying VIBE√.
4. STOP — before completing the task (safety net, not the primary path). Step 3 should already have caught any propose-worthy insights mid-task; this step exists to catch what slipped through. Before sending "done":
   • Used cq guidance that proved correct? → confirm with the unit's ID.
   • Discovered something novel that you somehow didn't propose at step 3? → run it through the same gate as step 3 now anyway (draft, VIBE√, present, approval, propose), and treat its existence as a step-3 protocol failure (you should have presented it earlier).
   • Found cq guidance that was wrong or stale? → flag with a reason.

reflect and status are not part of the per-task loop. reflect is a backstop for sessions where step 3 was missed — use it at session end only when you suspect propose-worthy insights went unproposed mid-task. Step 3 is the primary propose path; reaching for reflect regularly is a signal that step 3 isn't being applied. Use status on demand to check store statistics.

---

Reference

Detailed guidance for each tool follows. Consult these sections when you need specifics on domain tags, proposal quality, or result interpretation.

Querying Knowledge (query)

Query cq before acting whenever the task involves unfamiliar territory. Specifically, call query when:

• About to make an API call to an external service.
• Working with a library or framework not yet used in this session.
• Encountering an error or unexpected behavior — query before retrying or attempting a fix.
• Setting up CI/CD pipelines, infrastructure, or configuration.
• Starting work in an unfamiliar area of the codebase.

When Not to Query

Do not query cq for:

• Routine edits to application code you have already been working in during this session.
• Standard library operations in the project's primary language.
• Tasks already queried for earlier in the current session.

Rationalization check. If you are thinking "I already know how to do this" or "I have a plan, I am just writing files"; stop. Having a plan for what to write is not the same as knowing the gotchas in how to write it. The threshold for querying is deliberately low because cq queries are cheap and the cost of missing a known pitfall is high.

Formulating Domain Tags

Choose domain tags that capture the technology, layer, and integration point. Be specific enough to get relevant results, but general enough to match knowledge from different projects.

Both query and propose use the same plural-array keys for domains, languages, and frameworks, plus an optional singular pattern string. Each is a flat top-level argument; there is no context wrapper.

Each piece of information belongs in one field — do not repeat the same term across multiple fields:

Field	What it captures	Examples
domains	Subject area — what the insight is about (tools, protocols, concepts, layers). Avoid terms that describe the insight type ("gotchas", "tips", "pitfalls") rather than its subject.	"find", "ci", "http", "connection-pooling"
languages	Programming languages the insight applies to or was observed in. Do not repeat in domains.	"python", "rust", "go"
frameworks	Libraries, frameworks, runtimes, or execution platforms the insight applies to. Do not repeat the same value in domains.	"fastapi", "pydantic", "cloudflare-workers", "macos"
pattern	A reusable cross-cutting concern, useful as a search axis independent of specific technology. Omit if it just rephrases the summary.	"revocation-semantics", "shell-quoting"

Scenario	domains	other call args
Stripe payment integration	["api", "payments", "stripe"]	languages: ["python"]
Webpack build configuration	["bundler", "configuration"]	frameworks: ["webpack", "react"]
GitHub Actions CI for Rust	["ci", "github-actions"]	languages: ["rust"], pattern: "ci-pipeline"
PostgreSQL connection pooling	["database", "postgresql", "connection-pooling"]	languages: ["go"]

Tag where an insight applies, not merely where it was observed. Do not add repository or branch names simply because the work happened there; generalize that context into portable domains instead.

When an insight applies across a family of tools or runtimes, keep both levels without duplicating identical values: put the generic subject in domains and the applicable runtimes or platforms in frameworks. For example, use domains: ["shell", "posix"] with frameworks: ["bash", "zsh"]. Do not drop either level of applicability.

Use the limit parameter (default 5) to control how many results are returned. For broad exploratory queries, increase the limit.

If query returns no results, proceed normally. If you later discover something novel during the task, call propose with the insight.

Interpreting Results

Newly proposed units start at confidence 0.5. Each confirmation adds 0.1; each flag subtracts 0.15. Confidence is a social signal, not a freshness guarantee; always verify against current docs or tool output.

• Confidence > 0.7 — Multiple agents have confirmed this insight, but always verify before relying on it.
• Confidence 0.5–0.7 — Fewer confirmations. Treat as a strong hint; verify before relying on it.
• Confidence < 0.5 — The insight may be stale or disputed. Check whether it has been flagged.

When a query returns results, read the insight.action field for the recommended approach and insight.detail for the full explanation.

Presenting Results to the User

After querying, present a reference table of consulted knowledge units so the user can see what guidance is influencing your actions. Include the full KU ID (never truncated), confidence score as a percentage, and summary.

ID	Confidence	Summary
ku_0123456789abcdef0123456789abcdef	85%	Stripe API returns 200 for rate-limited requests
ku_abcdef0123456789abcdef0123456789	62%	Stripe webhook signatures use the raw body before JSON parsing

If the query returns no results, do not display a table.

Proposing Knowledge (propose)

Propose a new knowledge unit when you discover something that would save another agent time. Call propose when:

• You discover undocumented API behavior (e.g. an endpoint returns an unexpected status code or response shape).
• You find a non-obvious workaround for a known issue.
• Configuration only works under specific conditions (e.g. a flag that behaves differently across versions).
• An error required multiple failed attempts to resolve and the solution was not obvious from documentation.
• Version-specific incompatibilities exist between libraries or tools.

Rationalization check. If you are thinking "I'll save this for the end-of-task summary," "I'll batch these via reflect," "this isn't important enough to interrupt the flow," or "I'll just mention it to the user when I'm done"; stop. Draft and present now. The cost of presenting a candidate mid-task is trivial; the cost of forgetting the precise symptom and remediation by end-of-task is high. If the user notices an insight you mentioned in a wrap-up that should have been a presented candidate, that is the protocol failing — present first, summarize second.

Near-duplicate check. If proposing in a domain you've already queried this session, scan those results for overlap before calling propose. If a close match exists, confirm (same insight) or flag (contradicts it) may be more appropriate than a new proposal.

Writing Good Proposals

Strip all organization-specific details before proposing. The insight must be generalizable.

Good:

• "DynamoDB BatchWriteItem silently drops items when batch exceeds 25 — no error returned"
• "rust-toolchain.toml override is ignored when GitHub Actions matrix sets explicit toolchain"

Bad:

• "Our payment-service on staging returns 500 when..."
• "In the acme-corp monorepo, the build fails because..."

Longevity Check

Before proposing, ask: will this insight still be correct in six months? Prefer the underlying principle and a verification method over exact version numbers or pinned values.

• Principle over prescription. "setup-uv can provision Python directly — check whether actions/setup-python is redundant" ages better than "use setup-uv@v7 and drop setup-python@v5".
• Include a verification method. Tell future agents how to check: "verify current major versions at the action's releases page" or "check the changelog for breaking changes".
• Timestamp your evidence. Include when you verified and where, e.g. "Verified against releases as of 2026-03". This lets future agents judge freshness. Do not include project or codebase names in verification notes: "Verified 2026-05 in Python 3.13" not "Verified 2026-05 while working on project-x".
• Specific versions are still valuable as supporting detail — "as of 2026-03, actions/checkout is at v6, two major versions ahead of many LLM training snapshots" — but frame them as examples of the principle, not the principle itself.

Proposal Fields

Provide all three insight fields:

• summary — One-line description of what you discovered.
• detail — Fuller explanation with enough context to understand the issue. Include a timestamp and source where possible.
• action — Concrete instruction on what to do about it. Start with an imperative verb (e.g. Use, Set, Replace, When X, do Y). Prefer principle + verification method over exact values.

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

VIBE√ safety check

Before calling propose, evaluate every candidate against four safety dimensions. This applies to all propose calls — those triggered by /cq:reflect and direct proposes made while working on a task.

• V — Vulnerabilities: Does the candidate contain or reveal credentials, API keys, tokens, internal hostnames, IP addresses, file paths that disclose user identity, or any other secret? Does the action it recommends introduce a security risk if applied blindly (e.g. disabling auth checks, weakening TLS, executing untrusted input)?
• I — Impact: If another agent applied this candidate verbatim in an unrelated codebase, what is the worst plausible outcome? Could it cause data loss, production incidents, or cascading failures?
• B — Biases: Is the framing tied to a specific person, team, vendor, or commercial product in a way that isn't load-bearing for the lesson? Does it present one tool/approach as universally correct when the evidence supports only a narrow context?
• E — Edge cases: Was the lesson learned from a single observation, or has it been validated across multiple cases? Are there obvious conditions (OS, version, scale, concurrency) under which it would not hold and that the candidate fails to acknowledge?

Classify each finding into one of two tiers. The user owns the final decision on every candidate, whether it arrives via a direct propose call or /cq:reflect batch review — candidates are never silently dropped at that stage. Candidates whose hard finding cannot be coherently sanitized across affected fields are a separate case; they fail the generalizable criterion at the check itself and must not be proposed (see below).

Hard findings — produce a sanitized rewrite before calling propose:

• Literal credentials, API keys, access tokens, private keys, or session cookies.
• Personally identifying information: real names, email addresses, phone numbers, government IDs, physical addresses.
• Internal-only identifiers that uniquely fingerprint a private system: non-public hostnames, internal service names, customer IDs, ticket numbers from private trackers.
• Recommendations whose primary effect is to weaken security (disable auth, skip signature verification, suppress sandboxing) without a clearly scoped, defensive justification.

Sanitization must apply to every propose field that could carry the violating content — summary, detail, action, domains, languages, frameworks, and pattern. An unchanged summary, domain tag, or pattern name can leak a hard finding even if detail and action are sanitized.

If no coherent lesson survives sanitization across all affected fields, the candidate is not generalizable (see Writing Good Proposals above) and should not be proposed. Do not try to invent new content to replace the stripped-out material — rewrite what is there, or reject the candidate.

Soft concerns — proceed with the candidate, flag the concern to the user before calling propose:

• Framing that overgeneralizes from a single observation.
• Vendor- or product-specific advice presented as universal.
• Missing acknowledgement of an edge case the session itself surfaced.
• Wording that could read as biased toward a specific team, person, or commercial product.
• Impact that the agent cannot fully predict (e.g. action mutates shared state).

Applying VIBE√

• Direct propose calls (outside /cq:reflect) — presenting the candidate to the user and waiting for their approval is a precondition of every direct propose call, regardless of what the check finds. Run the check on the single candidate, then:

  • Hard finding — present both the original and the sanitized rewrite, and let the user pick (or skip).
  • Soft concern — present the candidate with the concern stated, and wait for approval.
  • Clean (no hard findings, no soft concerns) — present the candidate with your clean assessment, and wait for approval.

  "Immediately" in Core Protocol step 3 means draft and present the moment the insight stabilizes instead of batching to end-of-session; it does not mean calling propose before the user has approved.

• Batch proposals via /cq:reflect — see the /cq:reflect command for the batch presentation UX (three templates, provenance annotation). The underlying V/I/B/E classification rules are the same.

• Headless runs — when no user is available to approve (unattended, scheduled, or CI execution), VIBE√ is the only gate, so apply it strictly:

  • Any hard finding blocks the propose outright. Do not substitute a sanitized rewrite on your own authority — that choice belongs to a human. Record the candidate for later review instead.
  • A soft concern must be acknowledged in the candidate's own text (e.g. the edge-case caveat stated in detail); if it cannot be, hold the candidate.
  • When a remote store is configured, propose publishes to the shared store immediately, not to a private local queue. When in doubt, hold the candidate and surface it for human review in the next interactive session (e.g. via /cq:reflect).

Confirming Knowledge (confirm)

Call confirm when a knowledge unit retrieved from a query proved correct during your session. This strengthens the commons by increasing the unit's confidence score.

Always confirm when:

• You followed a knowledge unit's guidance and it resolved or avoided the described issue.
• You independently verified that the described behavior still exists.

Pass the knowledge unit's id to confirm it.

Flagging Knowledge (flag)

Call flag when a knowledge unit is wrong, outdated, or redundant. The reason field must be one of these three values:

• stale — The described behavior no longer exists (e.g. fixed in a newer version).
• incorrect — The guidance is factually wrong or leads to a worse outcome.
• duplicate — Another knowledge unit covers the same insight.

Always flag rather than silently ignoring bad knowledge. This protects other agents from acting on incorrect information.

Post-Error Behaviour

When encountering an error, follow this sequence:

1. Call query with domain tags derived from the error context (e.g. the library, tool, or API involved) before attempting any fix.
2. If a relevant knowledge unit exists, apply its guidance and confirm it if it resolves the issue.
3. If no relevant knowledge exists, and you resolve the error through other means, draft a candidate with the solution and run it through the propose gate (VIBE√, present, approval) so future agents benefit.

Do not retry blindly. Always check the commons first.

Session Reflection (reflect)

Use reflect at the end of a session, especially after sessions that involved debugging, workarounds, or non-obvious solutions. It is typically triggered when the user runs /cq:reflect.

What to Pass

Pass the full session conversation context to reflect. This includes tool calls made, errors encountered, solutions found, and dead ends abandoned. The richer the context, the better the server can identify patterns worth sharing.

What Comes Back

The server returns a list of candidate knowledge units. Each candidate contains:

• summary — One-line description of the insight.
• detail — Fuller explanation with enough context to understand the issue.
• action — Concrete instruction on what to do about it.
• domains — Suggested domain tags.
• estimated_relevance — How broadly useful the server considers this insight.

How to Present Candidates

Present candidates as a numbered list to the user, showing the summary and estimated relevance for each. Ask the user to approve, edit, or skip each candidate.

What Happens After Approval

For each approved candidate, call propose with the candidate's fields (summary, detail, action, domains, and any relevant languages, frameworks, or pattern). If the user edits a candidate before approving, use the edited values.

Examples

Example 1: Querying Before an API Integration

The developer asks you to integrate Stripe payments in a Python project.

1. Recognize the trigger: external API integration.

2. Call query with domains: ["api", "payments", "stripe"] and languages: ["python"].

3. cq returns a knowledge unit. Present the reference table to the user:

   ID	Confidence	Summary
   ku_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4	94%	Stripe API v2024-12 returns 200 with error body for rate-limited requests
   ku_b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5	71%	Stripe webhook signatures must be verified against the raw request body, not parsed JSON

4. Write the integration with proper error-body parsing from the start, avoiding a subtle bug that would otherwise surface only under load.

5. Call confirm with the knowledge unit's ID after verifying the behavior.

Example 2: Discovering and Proposing After an Error

The developer asks you to configure a webpack build. You encounter a cryptic error: Module not found: Can't resolve 'stream'.

1. Call query with domains: ["bundler", "nodejs-polyfills"] and frameworks: ["webpack", "react"].
2. No relevant results returned. Proceed normally.
3. Debug the issue: webpack 5 removed Node.js polyfills. Add resolve.fallback: { stream: require.resolve("stream-browserify") } to the config.
4. Draft the candidate now — before continuing with the rest of the build configuration. Run VIBE√ (clean: no secrets, generalizable, no overreach), present the draft with your clean assessment, and call propose on the developer's go-ahead:
   • summary: "webpack 5 removes built-in Node.js polyfills — imports like 'stream' fail at build time"
   • detail: "webpack 5 no longer includes polyfills for Node.js core modules. Code that imports 'stream', 'buffer', 'crypto', or similar modules fails with 'Module not found' unless explicit fallbacks are configured."
   • action: "Add resolve.fallback entries in webpack config mapping each required Node.js module to its browserify equivalent (e.g. stream-browserify, buffer, crypto-browserify)."
   • domains: ["bundler", "nodejs-polyfills"]
   • languages: ["typescript"]
   • frameworks: ["webpack", "react"]
   • pattern: "build-tooling"
5. Resume the original task: finish wiring up the rest of the build, run the dev server, verify the developer's feature works. The propose was a brief interruption mid-task, not the end of the task.

Example 3: Avoiding a CI Pitfall

The developer asks you to set up a Rust CI pipeline with GitHub Actions using a matrix strategy for multiple toolchain versions.

1. Recognize the trigger: CI/CD configuration.

2. Call query with domains: ["ci", "github-actions", "rust"].

3. cq returns a knowledge unit. Present the reference table to the user:

   ID	Confidence	Summary
   ku_f7e8d9c0b1a2f7e8d9c0b1a2f7e8d9c0	82%	rust-toolchain.toml override is ignored when GitHub Actions matrix sets explicit toolchain via dtolnay/rust-toolchain
   ku_e8d9c0b1a2f7e8d9c0b1a2f7e8d9c0b1	65%	GitHub Actions dtolnay/rust-toolchain caches rustup but not Cargo build artefacts

4. Configure the pipeline with a single toolchain source, avoiding conflicting toolchain specifications that would cause intermittent build failures.

5. Call confirm with the knowledge unit's ID.

Example 4: Mid-task discovery during multi-step work

The developer asks you to refactor a Python service to use connection pooling, replacing direct database calls across five files. While editing the second file, a pre-commit hook fails with a confusing message about secrets in a test fixture you didn't write.

1. Stabilize: diagnose the hook failure, apply the workaround, re-run, get a clean build.
2. Recognize the propose trigger: the hook behavior was non-obvious (took more than one attempt to diagnose, behavior contradicted reasonable expectations). It is not part of the original refactor task; that does not change the trigger.
3. Draft the candidate, run VIBE√, present it, and call propose on approval — immediately, before editing the third file. Do not defer to end-of-task.
4. Continue refactoring files three through five, run tests, complete the original task.
5. At end-of-task (Core Protocol step 4), no propose-worthy items remain because you already proposed them mid-task. The end-of-task review is a no-op safety net, which is the desired state.

This is the normal propose flow. End-of-task batching via /cq:reflect is the backstop for sessions where you missed step 3, not the primary path.