drhalto/agentmako/mako-guide

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.