/mako-guide

description: >-
  Start here when working in a project with the mako-ai MCP server configured.
  Entry point that explains how mako's tool skills are organized and carries
  the policy for logging `agent_feedback` vs acknowledging static findings with
  `finding_ack`.
when_to_use: >-
  Use when starting a Mako-backed investigation, deciding which Mako skill to
  invoke, deciding whether to log tool feedback, or deciding whether a static
  finding should be acknowledged.
allowed-tools: "mcp__mako-ai__*"

Mako Guide

Mako is a project-intelligence MCP server. Use it when the user asks structural, cross-surface, or evidence-backed engineering questions that are better answered from indexed code, schemas, routes, graph edges, prior sessions, or telemetry than from ad hoc file reads.

Do not use this skill as a schema reference. For current tool schemas, use MCP ToolSearch or the live tool definition loaded by Claude Code.

Skill Map

• Use `/mako-ai:mako-discovery` for first-turn orientation, broad search, and

"which tool should I use?" questions.

• Use `/mako-ai:mako-trace` for targeted route, schema, file, table, RPC, edge,

auth, or error tracing.

• Use `/mako-ai:mako-neighborhoods` for one-call table, route, or RPC context

bundles.

• Use `/mako-ai:mako-graph` for relationships, dependency paths, import impact,

symbol impact, flow mapping, and change planning.

• Use `/mako-ai:mako-database` for direct database schema, RLS, foreign-key, or

RPC introspection.

• Use `/mako-ai:mako-code-intel` for structural AST pattern search and focused

lint diagnostics.

• Use `/mako-ai:mako-workflow` for investigation packets, artifacts, recall,

telemetry inspection, feedback, and finding acknowledgements.

General Routing Rules

• Read `_hints` on every Mako tool result before deciding the next call. They

are generated from the actual returned result and may override the generic workflow expectation.

• Default to `reef_ask` for project questions. It combines codebase, database,

findings, diagnostics, instructions, freshness, and quoted literal checks.

• Use `mako_help` when you need a task-specific Mako workflow recipe instead

of reading docs or guessing which specialist tool to load.

• Use `context_packet`, `cross_search`, `file_preflight`, DB tools, and graph

tools as specialist follow-ups after `reef_ask`, `mako_help`, or `tool_search` points at a concrete need.

• Prefer Mako over built-in grep when the question is about relationships,

not literal text.

• Built-in text search is fine for exact strings inside known files.
• Start broad only when the target is unknown; switch to targeted tools once

you have a route, table, RPC, file, or symbol.

• Do not invent schemas, arguments, request IDs, finding fingerprints, or

telemetry events.

• If a tool name is uncertain, use `tool_search` before calling a Mako tool.

Feedback Logging Policy

Log `agent_feedback` selectively when a Mako result is notably useful, partially useful, noisy, stale, incomplete, wrong, or wasted the turn. Do not emit routine feedback after every tool call.

Before calling `agent_feedback`:

1. Call `recall_tool_runs`. 2. Filter by `toolName` and a recent ISO time window when possible. 3. Use a small `limit` first. 4. Copy the recalled `requestId` into `referencedRequestId`. 5. Set `referencedToolName` to the tool being rated. 6. Use `grade: "full" | "partial" | "no"`. 7. Include concise `reasonCodes` and a short human-readable `reason`.

If no `requestId` is available, do not fabricate one. Refine `recall_tool_runs` or skip feedback.

Use these starter reason codes exactly when they fit:

• `grade: "full"`: `answer_complete`, `evidence_sufficient`,

`trust_matches`

• `grade: "partial"`: `partial_coverage`, `noisy`, `stale_evidence`,

`missing_known_caller`, `top_not_useful`

• `grade: "no"`: `answer_wrong`, `wasted_turn`, `tool_did_nothing`,

`schema_missing`

The reason-code vocabulary is guidance, not a hard enum. New snake_case codes are acceptable when none of the starter codes fit.

Finding Acks Are Different

Use `finding_ack` for reviewed static findings, not for tool usefulness.

• Use `agent_feedback` to rate a specific Mako tool run.
• Use `finding_ack` to acknowledge a specific AST/lint/static finding as

reviewed, accepted-risk, false-positive, or otherwise handled.

• Do not use `finding_ack` to rate search quality.
• Do not use `agent_feedback` to suppress or accept a static finding.

Telemetry Inspection

Use `agent_feedback_report` and `runtime_telemetry_report` for inspection:

• confirm feedback capture worked;
• summarize tool quality over a window;
• debug whether a live session recorded events;
• prepare roadmap or implementation review notes.

Do not use telemetry reports as an automatic ranking system for tool selection unless Mako explicitly implements that behavior.