drhalto/agentmako/mako-discovery

Mako Discovery

Use this skill for orientation and broad discovery. Prefer it when the user has not yet named a precise file, route, table, RPC, or symbol. Default to reef_ask; load specialist tools only when Reef or tool_search identifies a concrete need.

Tools

tool_search

Use when the task intent is clear but the exact Mako tool name or schema is unknown.

• Use it to find the right Mako tool and load its live schema.
• Do not use it as the final answer when a domain tool should be called next.
• Pair it with the other skills when a result points to a trace, graph,

database, or workflow tool.

mako_help

Use when you know the task but not the Mako workflow order.

• Returns a task-specific recipe such as auth-flow audit, DB/RLS audit,

pre-edit file gate, review/verification, diagnostics triage, or general orientation.

• Each step includes toolName, suggestedArgs, whenToUse, readOnly, and

batchable.

• Use the returned batchHint to batch independent read-only follow-ups after

the first orientation call.

reef_ask

Use for the primary answer loop over codebase, database, findings, diagnostics, instructions, freshness, and quoted literal checks.

• Use for open-ended repo questions, planning questions, debugging questions,

where-used questions, database inventory questions, and known-finding questions.

• Pass focus or changedFiles when known.
• Read evidence, risks, freshness, missingEvidence, and nextQueries

before choosing any follow-up.

• Use evidenceMode: "full" only when compact evidence is insufficient.

Reef Loop Tools

Use these direct Reef adapters for the normal agent loop after reef_ask.

• reef_status: maintained issues, changed files, stale diagnostics, schema,

watcher state, and queue health.

• reef_verify: completion gate for diagnostic freshness and unresolved open

loops; read it before claiming work is verified.

• reef_impact: changed-file impact over downstream callers, invalidated

findings, and convention risks.

context_packet

Use when reef_ask needs raw ranked context expansion before reading or editing.

• Use mode: "explore" for discovery, "plan" before outlining

implementation work, "implement" before editing code, and "review" for verification or change review.

• Read modePolicy to understand which providers and follow-up tools were

emphasized.

• Read _hints, freshnessGate, risks, scopedInstructions, and

expandableTools before choosing the next call.

live_text_search

Use when exact current disk text matters more than indexed/project knowledge.

• Use for regex, custom globs, generated or unindexed files, and raw full

inventories.

• For bounded quoted literal checks, prefer reef_ask first.

Specialist discovery

Use tool_search for specialist tools such as repo_map, cross_search, ast_find_pattern, reef_scout, route/table/RPC neighborhoods, graph tools, DB inspection, or finding/ack workflows.

• Do not load specialist tools just to browse the catalog.
• Prefer reef_ask or mako_help first unless the exact specialist target is

already known.

project_conventions

Use to learn project-specific habits before changing risky surfaces.

• Returns explicit Reef convention facts plus conventions derived from the

project profile, indexed auth-like symbols, routes, generated files, schema usage, and rules.

• Useful kinds include auth_guard, runtime_boundary, generated_path,

route_pattern, and schema_pattern.

• Use before auth, routing, generated-file, or database-touching edits when the

local conventions are unclear.

file_preflight

Use before editing a known risky file.

• Returns durable findings, file-scoped diagnostic freshness, recent diagnostic

runs, watcher diagnostic state, applicable conventions, and finding acknowledgement history in one packet.

• With sources, recent diagnostic runs are filtered to those sources. For

file-scoped checks, only project-wide runs or runs whose requestedFiles include the file count as covering it.

• Use instead of chaining file_findings, verification_state,

project_conventions, and ack-history calls when the question is "what should I know before changing this file?"

• Use reef_inspect only when a returned finding or fact needs deeper

evidence.

reef_impact

Use mid-edit or before review when changed files may affect callers.

• Pass filePaths for the working-tree files you changed.
• Returns downstream import callers, active findings on those callers that may

need re-checking, and applicable convention risks.

• It is read-only and does not run working_tree_overlay; if overlay facts are

missing, call working_tree_overlay or wait for the watcher first.

• reef_diff_impact remains the lower-level compatibility name for the same

calculation.

Feedback Logging

Log agent_feedback when a result here was notably useful, partial, noisy, stale, wrong, or wasted the turn. Skip routine calls.

Required procedure (see /mako-ai:mako-guide for full rules and reason-code vocabulary):

1. Call recall_tool_runs to get the prior run's requestId. Do not

fabricate one — if no run is recalled, skip feedback.

1. Call agent_feedback with referencedToolName,

referencedRequestId, grade: "full" | "partial" | "no", reasonCodes from the starter vocabulary in /mako-ai:mako-guide, and a short reason.

See Also

• Use /mako-ai:mako-trace after discovery identifies a concrete target.
• Use /mako-ai:mako-neighborhoods when the target is a table, route, or RPC

and the user needs bundled surrounding context.

• Use /mako-ai:mako-graph for dependency paths and blast radius.