OutlineDriven Explore
Contract
| Field | Bound contract |
|---|---|
| Trigger | User says "explore", "find where X is", "how does X work in the code", or "map the codebase" for repo-local orientation. |
| Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. |
| Side effect | A structured orientation report in chat; may dispatch Explore subagents. No state mutation. |
| Done | All 8 output sections emitted or applicability stated, scope declared, and dispatch/escalation rules followed. |
Inputs
- Task text (supplied): the orientation question or concern to map.
- Repo working tree (supplied by environment): read-only access to the local checkout.
- Optional: specific files, directories, or concerns used to bound scope before dispatch.
Procedure
- Scope. Parse the task; identify the files, directories, and concerns in scope. State the scope explicitly before any dispatch or read. Done when: the scope is stated explicitly before any dispatch or read.
- Dispatch decision. For multi-file or uncertain tasks, dispatch Explore subagents instead of reading directly. Escalation: 1 subagent for a single-concern known scope; 3 subagents for multiple concerns or unknown scope; 5 subagents for a cross-module or architectural survey. Auto-skip (direct reads allowed) only for a single file under 50 LOC. Dispatch first; do not grep or glob a multi-file task before dispatching. Done when: the dispatch decision is made with the correct escalation tier, or direct reads are selected for a single file under 50 LOC.
- Discovery with token-efficient flags. File discovery:
fd -e <ext> --max-results 50. Symbol search:ast-grep run -p 'PATTERN' -l <lang> -C 1orgit --no-pager grep -n -C 2 'pattern'. Content preview:bat -P -p -n -r START:END fileor read with offset/limit. Directory structure:eza --tree --level=2. Done when: discovery is completed using token-efficient flags. - Synthesis. Emit all 8 output sections below. Omit a section only when genuinely not applicable and state why. Done when: all 8 output sections are emitted or omitted with a stated reason.
- Heavy-codebase escape hatch. When scope exceeds 50 files, use a codebase-packing tool only as an internal analysis aid; never give packed output to the user. Search the packed output for targeted extraction. If no packing tool is available, narrow scope and state the narrowing. Done when: the heavy-codebase escape hatch is applied or scope is narrowed with a stated reason.
- Tool restrictions. Allowed (read-only):
eza,fd,ast-grep(find-only),git grep,rg,bat,tokei,Read,codebase_search, and any available codebase-analysis or codebase-packing MCP tooling. Banned:Edit,Write,mcp__edit__edit_file,git commit, and any state-mutating bash command. Done when: only allowed tools are used and no banned tool is invoked. - Recursion guard. Do not re-enter a router or orchestrator skill from within this leaf skill. Done when: no router or orchestrator skill is re-entered.
Failure and recovery
- Scope too large (> 50 files). Apply the heavy-codebase escape hatch; if no packing tool is available, narrow scope, state the narrowing, and proceed with the reduced scope.
- Empty or missing source. For each affected section, state that it does not apply and explain why rather than fabricating content.
- Dispatch failure. Return a partial result containing the sections that could be filled; never claim the done predicate holds when required sections are missing.
- Banned mutating tool attempted. Stop immediately, do not perform the mutation, and report the attempt. No rollback is needed because no mutation occurs.
- Blocked / non-converged result. Terminal classification stating which sections could not be filled and the concrete reason.
Output
A structured orientation report with 8 sections in order: task understanding, architecture context, pattern context, tooling context, dependency map, critical files summary, constraints and considerations, and recommended next steps, omitting a section only when not applicable with a stated reason.