/nav-brief

name: nav-brief
description: Render a one-screen intent brief (Goal/Scope/Approach/Limits/Verify/Won't-do) before implementing ambiguous task-shaped prompts, triggered by the nav_brief.py UserPromptSubmit hook. Confirms scope with max 2 open questions before touching files; detects brief drift mid-task.
version: 1.0.0

Navigator Intent Brief Skill

Front-load the scope negotiation. When a prompt is task-shaped but ambiguous, render a one-screen INTENT BRIEF and get confirmation **before** writing code — turning 2-4 correction exchanges into 1 confirmation exchange.

Why This Exists

Ambiguity is not complexity. A small task can be highly ambiguous ("fix the bug" — which bug?) while a large one can be fully specified. The expensive failure mode is implementing on guessed scope: rework burns tokens on undo/redo, pollutes context with dead ends, and forces mid-feature compacts.

When This Fires

**Hook contract**: render a brief ONLY when this turn's injected context contains a `NAV-BRIEF` reminder block (emitted by `hooks/nav_brief.py` on UserPromptSubmit when ambiguity score >= threshold). Never self-trigger from your own judgment alone — the hook is the single trigger source, so behavior stays predictable and tunable via config.

Config (`.agent/.nav-config.json`):

"brief_hook": {
  "enabled": true,
  "ambiguity_threshold": 0.5,
  "memory_budget_chars": 1200
}

Rendering the Brief

Use the template below. Pre-fill every field you can from the injected `## Relevant Memories` section and current session context; mark assumptions explicitly.

┌─ BRIEF: <short title> ──────────────────────────────┐
│ Goal      <outcome, one line>                       │
│ Scope     <files/dirs/endpoints — concrete>         │
│           NOT <adjacent things left untouched>      │
│ Approach  <how — cite memory if pre-filled>         │
│ Limits    <numbers, constraints — mark ASSUMED>     │
│ Verify    <how completion will be proven>           │
│ Won't do  <explicit non-goals>                      │
└─────────────────────────────────────────────────────┘
Confirm / edit? (open questions: <0-2>)

Rules:

• **Max 2 open questions.** Ask only what you cannot infer or safely assume;

everything else is a pre-filled default the user can veto.

• **Stop and wait** for user confirmation before any Edit/Write/Bash that

modifies the project.

• After confirmation, capture corrections: changed defaults are candidate

knowledge-graph memories (`"Remember we decided..."` flow via nav-graph), so future briefs pre-fill better.

Passthrough Rules (do NOT render a brief)

• No `NAV-BRIEF` reminder in this turn's context.
• The prompt is plainly an **answer to a pending brief's open questions**

(model-side judgment — the hook is stateless in v1 and may re-fire on answers that contain task verbs; known limitation).

• User signals urgency/override: "just do it", "quick fix", "skip the brief".

Respect it silently.

Brief Drift Detection

Mid-implementation, if the work is about to exceed the confirmed brief's Scope or Limits (touching files outside scope, changing an untouched-by- agreement area), STOP and surface:

⚠ BRIEF DRIFT: <what exceeds the brief, one line>
Options: extend brief / skip this change

One question, then continue per the answer.

Interaction with workflow_enforcer / Task Mode

Both UserPromptSubmit hooks may fire on the same prompt. Show both blocks — they are complementary: WORKFLOW CHECK decides *how* to execute (mode), the brief decides *what* is in scope. In Task Mode, the confirmed brief replaces ad-hoc scope derivation in the PLAN phase.

Examples

**Brief rendered** — `"add rate limiting to the API"` (score 0.7): brief with Scope pre-filled to public routes (graph memory), Limits marked ASSUMED, 1 open question about limit numbers. User answers; implementation starts.

**Passthrough** — `"fix the typo in README.md"` (score 0.1): file reference gives full scope; no brief, direct execution.

**Drift** — brief confirmed scope `/api/public/*`; implementation later needs a shared middleware file used by internal routes → BRIEF DRIFT raised, user extends the brief.

Future Work (explicitly deferred from v1)

• Statefulness: persist pending-brief state across turns (removes the

answer-re-fire limitation).

• `strict_block`: hard-gate implementation until a brief is confirmed.
• Measurement: briefs-shown/passthrough counters + corrections-per-task

metrics (pairs with nav-stats; deferred until there is a consumer).

• Prompt rewriting.