diff --git a/manuals/reflect.md b/manuals/reflect.md index 28f83a2..a455921 100644 --- a/manuals/reflect.md +++ b/manuals/reflect.md @@ -40,8 +40,9 @@ - **Ambiguity:** Use it when a user request is vague or could be interpreted in multiple ways. ### When NOT to use `reflect` -- **Simple Tasks:** Do not use it for single-step operations (e. +- **Simple Tasks:** Do not use it for single-step operations. - **Routine Actions:** Do not use it for standard file reads, writes, or simple searches. +- **Before Basic Fact Gathering:** Do not use it as a substitute for checking `NAVI.md`, docs, files, tool schemas, or obvious command output. ### The Importance of `assumptions` The most critical input to the `reflect` tool is the `assumptions` parameter. @@ -49,6 +50,18 @@ - **Be brutally honest.** List everything you are taking for granted (e.g., "I assume the user has sudo access", "I assume the file exists in the workspace directory"). - **The act of listing assumptions often reveals the solution to the problem itself.** +## Autonomy Rule + +If reflection finds missing information, resolve it through available sources first: +- nearest `NAVI.md` +- project docs or manuals +- memory +- source files and tool schemas +- command output +- web research when current external facts matter + +Ask the user only when the missing decision is genuinely theirs to make or cannot be recovered from available sources. + ## Example Input/Output Flow **Input:** @@ -56,6 +69,6 @@ - **Assumptions:** ["The server is reachable via SSH", "The user has the necessary keys configured", "The Docker daemon is running"] **Output:** -- **Critic:** "You haven't mentioned how you will handle credential rotation or if the SSH key is protected by a passphrase." -- **Pragmatist:** "Instead of a full automation script, just use a simple `docker compose up` command via SSH to start." -- **Detailer:** "You need to check if the remote user has permissions to the `docker` group and ensure the network port is open in the firewall." +- **Critic:** "You haven't mentioned how you will handle credential rotation or whether the SSH key is protected by a passphrase." +- **Pragmatist:** "Instead of a full automation script, use the existing deployment command if the project docs or NAVI.md define one." +- **Detailer:** "Check whether the remote user has Docker permissions and whether the required network port is open before changing deployment logic." diff --git a/navi/tools/reflect.py b/navi/tools/reflect.py index 72776d5..87c6388 100644 --- a/navi/tools/reflect.py +++ b/navi/tools/reflect.py @@ -26,7 +26,8 @@ - What is being taken for granted that should be questioned? Be direct and specific. Do not be encouraging. Name concrete problems, not abstract concerns. -Keep your response concise — 3 to 6 sharp points.""" +Do not invent missing facts. If evidence is needed, say exactly what to verify. +Keep your response concise: 3 to 6 sharp points.""" _PRAGMATIST_SYSTEM = """\ You are a pragmatic advisor. Your role is to find the simplest, most direct path to the goal. @@ -38,7 +39,8 @@ - Is the stated goal actually the real goal, or is there a simpler reframing? Challenge over-engineering. Propose concrete simplifications. -Keep your response concise — 3 to 6 actionable points.""" +Prefer actions that gather missing information before asking the user. +Keep your response concise: 3 to 6 actionable points.""" _DETAILER_SYSTEM = """\ You are a detail-oriented advisor. Your role is to find what is missing, ambiguous, or underspecified. @@ -50,7 +52,8 @@ - What information is missing before a good decision can be made? Be specific about what is absent, not just that something might be missing. -Keep your response concise — 3 to 6 concrete gaps.""" +For each important gap, say whether to resolve it by checking docs/files/tools/web or by asking the user. +Keep your response concise: 3 to 6 concrete gaps.""" # ── Prompt builder ───────────────────────────────────────────────────────── @@ -143,18 +146,18 @@ output = ( "# Reflection\n\n" - "## 🔴 Critic\n" + "## Critic\n" f"{critic}\n\n" - "## 🟡 Pragmatist\n" + "## Pragmatist\n" f"{pragmatist}\n\n" - "## 🔵 Detailer\n" + "## Detailer\n" f"{detailer}\n\n" "---\n" "Integrate these perspectives into your plan.\n" - "MANDATORY: If the Detailer identified ambiguities that affect the core direction " - "(what to build, which approach, what the user actually wants) — " - "stop and ask the user to clarify BEFORE writing any code or executing a plan. " - "Do not resolve strategic ambiguities by assumption.\n" + "First resolve missing information through available sources: NAVI.md, docs, manuals, " + "memory, files, tool schemas, command output, or web research. " + "Ask the user only when the missing decision is genuinely theirs to make or cannot be " + "recovered from available sources. " "Prioritise addressing points raised by the Critic before proceeding." )