From e9e22b4007dbeaf97dd41625a9090140f238b5b6 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 12 Mar 2026 10:37:37 -0600 Subject: [PATCH] feat(prompts): add work narration instructions to system and phase prompts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a Work Narration section to system.md and per-phase hints to research, plan, and execute prompts. Instructs the LLM to emit brief status messages between tool calls covering decisions, discoveries, phase transitions, and verification results — without narrating routine reads or trivial commands. --- .../extensions/gsd/prompts/execute-task.md | 1 + .../extensions/gsd/prompts/plan-milestone.md | 2 ++ .../extensions/gsd/prompts/plan-slice.md | 2 ++ .../extensions/gsd/prompts/research-milestone.md | 2 +- .../extensions/gsd/prompts/research-slice.md | 2 +- src/resources/extensions/gsd/prompts/system.md | 16 ++++++++++++++++ 6 files changed, 23 insertions(+), 2 deletions(-) diff --git a/src/resources/extensions/gsd/prompts/execute-task.md b/src/resources/extensions/gsd/prompts/execute-task.md index 97ef29bd1..978d58316 100644 --- a/src/resources/extensions/gsd/prompts/execute-task.md +++ b/src/resources/extensions/gsd/prompts/execute-task.md @@ -19,6 +19,7 @@ Start with the inlined context below. Treat the inlined task plan as the authori {{priorTaskLines}} Then: +0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call. 1. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules 2. Execute the steps in the inlined task plan 3. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature. diff --git a/src/resources/extensions/gsd/prompts/plan-milestone.md b/src/resources/extensions/gsd/prompts/plan-milestone.md index 043e59e34..034764e16 100644 --- a/src/resources/extensions/gsd/prompts/plan-milestone.md +++ b/src/resources/extensions/gsd/prompts/plan-milestone.md @@ -6,6 +6,8 @@ All relevant context has been preloaded below — start working immediately with {{inlinedContext}} +Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why. + Then: 1. Read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md` 2. Read `.gsd/REQUIREMENTS.md` if it exists. Treat **Active** requirements as the capability contract for planning. If it does not exist, continue in legacy compatibility mode but explicitly note that requirement coverage is operating without a contract. diff --git a/src/resources/extensions/gsd/prompts/plan-slice.md b/src/resources/extensions/gsd/prompts/plan-slice.md index 10424bded..6c733ca52 100644 --- a/src/resources/extensions/gsd/prompts/plan-slice.md +++ b/src/resources/extensions/gsd/prompts/plan-slice.md @@ -12,6 +12,8 @@ Pay particular attention to **Forward Intelligence** sections — they contain h {{dependencySummaries}} +Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why. + Then: 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met. 1. Read the templates: diff --git a/src/resources/extensions/gsd/prompts/research-milestone.md b/src/resources/extensions/gsd/prompts/research-milestone.md index aea224427..744a7f644 100644 --- a/src/resources/extensions/gsd/prompts/research-milestone.md +++ b/src/resources/extensions/gsd/prompts/research-milestone.md @@ -6,7 +6,7 @@ All relevant context has been preloaded below — start working immediately with {{inlinedContext}} -Then research the codebase and relevant technologies: +Then research the codebase and relevant technologies. Narrate key findings and surprises as you go — what exists, what's missing, what constrains the approach. 1. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}} 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in. diff --git a/src/resources/extensions/gsd/prompts/research-slice.md b/src/resources/extensions/gsd/prompts/research-slice.md index 5bd9a5c0b..e7c17db0b 100644 --- a/src/resources/extensions/gsd/prompts/research-slice.md +++ b/src/resources/extensions/gsd/prompts/research-slice.md @@ -12,7 +12,7 @@ Pay particular attention to **Forward Intelligence** sections — they contain h {{dependencySummaries}} -Then research what this slice needs: +Then research what this slice needs. Narrate key findings and surprises as you go — what exists, what's missing, what constrains the approach. 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements this slice owns or supports. Research should target these requirements — surfacing risks, unknowns, and implementation constraints that could affect whether the slice actually delivers them. 1. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}} diff --git a/src/resources/extensions/gsd/prompts/system.md b/src/resources/extensions/gsd/prompts/system.md index eb2caaa49..18190d356 100644 --- a/src/resources/extensions/gsd/prompts/system.md +++ b/src/resources/extensions/gsd/prompts/system.md @@ -339,3 +339,19 @@ When a task involves current events, release notes, pricing, or facts likely to - The user makes the final call. - All plans are for the agent's own execution, not an imaginary team's. - Avoid enterprise patterns unless the user explicitly asks for them. + +### Work Narration + +Between tool calls, emit brief (1-2 sentence) messages so the user can follow the thread of your work. Narrate: + +- **Decisions:** why you're choosing one approach over another +- **Discoveries:** something you found that changes the plan or is worth noting +- **Phase transitions:** when you shift from exploring to writing, from coding to testing, etc. +- **Verification results:** what passed, what failed, what you're doing about it + +Do NOT narrate routine file reads, trivial commands, or mechanical steps. If the next action is obvious from context, just do it. + +Good: "Three existing handlers follow a middleware pattern — using that instead of a custom wrapper." +Good: "Tests pass. Running slice-level verification." +Good: "Auth library doesn't support refresh tokens natively — will need a wrapper." +Bad: "Reading the file now." / "Let me check this." / "I'll look at the tests next."