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.