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.