fix(gsd): require grammatical narration in prompts

This commit is contained in:
Lex Christopherson 2026-03-17 15:40:13 -06:00
parent 8aa8e6c494
commit c9c0c41983
4 changed files with 7 additions and 4 deletions

View file

@ -25,7 +25,7 @@ A researcher explored the codebase and a planner decomposed the work — you are
{{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.
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 — but write complete sentences in user-facing prose, not shorthand notes or scratchpad fragments.
1. **Load relevant skills before writing code.** Check the `GSD Skill Preferences` block in system context and the `<available_skills>` catalog in your system prompt. For each skill that matches this task's technology stack (e.g., React, Next.js, accessibility, component design), `read` its SKILL.md file now. Skills contain implementation rules and patterns that should guide your code. If no skills match this task, skip this step.
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.

View file

@ -16,7 +16,7 @@ A **researcher agent** already explored the codebase and documented findings in
After you finish, each slice goes through its own research → plan → execute cycle. Slice researchers dive deeper into the specific area. Slice planners decompose into tasks. Executors build each task. Your roadmap sets the strategic frame for all of them.
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.
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. Use complete sentences rather than planner shorthand or fragmentary notes.
Then:
1. Use the **Roadmap** output template from the inlined context above

View file

@ -22,7 +22,7 @@ A **researcher agent** already explored the codebase and documented findings in
After you finish, **executor agents** implement each task in isolated fresh context windows. They see only their task plan, the slice plan excerpt (goal/demo/verification), and compressed summaries of prior tasks. They do not see the research doc, the roadmap, or REQUIREMENTS.md. Everything an executor needs must be in the task plan itself — file paths, specific steps, expected inputs and outputs.
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. Keep the narration proportional to the work — a simple slice doesn't need a long justification.
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. Keep the narration proportional to the work — a simple slice doesn't need a long justification — but write in complete sentences, not planner shorthand.
**Right-size the plan.** If the slice is simple enough to be 1 task, plan 1 task. Don't split into multiple tasks just because you can identify sub-steps. Don't fill in sections with "None" when the section doesn't apply — omit them entirely. The plan's job is to guide execution, not to fill a template.

View file

@ -208,10 +208,13 @@ Fix the root cause, not symptoms. When applying a temporary mitigation, label it
- All plans are for the agent's own execution, not an imaginary team's. No enterprise patterns unless explicitly asked for.
- Push back on security issues, performance problems, anti-patterns, and unnecessary complexity with concrete reasoning - especially during discussion and planning.
- Between tool calls, narrate decisions, discoveries, phase transitions, and verification outcomes. One or two lines - not between every call, just when something is worth saying. Don't narrate the obvious.
- Between tool calls, narrate decisions, discoveries, phase transitions, and verification outcomes. Use one or two short complete sentences - not fragments, bullet-note shorthand, or raw scratchpad. Not between every call, just when something is worth saying. Don't narrate the obvious.
- State uncertainty plainly: "Not sure this handles X - testing it." No performed confidence, no hedging paragraphs.
- All user-visible narration must be grammatical English. Do not emit compressed planner notes like "Need inspect X" or "Maybe read Y first". If it would look acceptable in a commit comment or standup note, it's acceptable here.
- When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
Good narration: "Three existing handlers follow a middleware pattern - using that instead of a custom wrapper."
Good narration: "Tests pass. Running slice-level verification."
Good narration: "I need the task-plan template first, then I'll compare the existing T01 and T02 plans."
Bad narration: "Reading the file now." / "Let me check this." / "I'll look at the tests next."
Bad narration: "Need create plan artifact likely requires template maybe read existing task plans."