From e97851ebd2ea81d5a669fd757e94fa1777cc3585 Mon Sep 17 00:00:00 2001 From: Dryade AI Date: Thu, 12 Mar 2026 18:35:51 +0100 Subject: [PATCH] feat: add mandatory read_first and acceptance_criteria to prevent shallow execution (#1013) Executor agents often produce shallow work because plans say "align X with Y" without specifying what the aligned result looks like. The executor changes one value and calls it done. This adds three mandatory fields to every task: - ``: Files the executor MUST read before editing. Ensures ground truth is loaded, not assumed. - ``: Grep-verifiable conditions checked after each task. No subjective language ("looks consistent"), only concrete checks ("file contains 'exact string'"). - `` guidance: Must include concrete values (identifiers, signatures, config keys), never vague references like "update to match production". Adds `` to planner instructions with mandatory quality gate checks. Executor workflow enforces both gates: read before edit, verify after edit. Adds generic pre-commit hook failure handling guidance. Co-authored-by: Dammerzone --- get-shit-done/templates/phase-prompt.md | 47 +++++++++++++++++++++++-- get-shit-done/workflows/execute-plan.md | 19 ++++++++++ get-shit-done/workflows/plan-phase.md | 34 +++++++++++++++++- 3 files changed, 96 insertions(+), 4 deletions(-) diff --git a/get-shit-done/templates/phase-prompt.md b/get-shit-done/templates/phase-prompt.md index 202a50236..6d23160dd 100644 --- a/get-shit-done/templates/phase-prompt.md +++ b/get-shit-done/templates/phase-prompt.md @@ -63,21 +63,29 @@ Output: [What artifacts will be created] Task 1: [Action-oriented name] path/to/file.ext, another/file.ext - [Specific implementation - what to do, how to do it, what to avoid and WHY] + path/to/reference.ext, path/to/source-of-truth.ext + [Specific implementation - what to do, how to do it, what to avoid and WHY. Include CONCRETE values: exact identifiers, parameters, expected outputs, file paths, command arguments. Never say "align X with Y" without specifying the exact target state.] [Command or check to prove it worked] + + - [Grep-verifiable condition: "file.ext contains 'exact string'"] + - [Measurable condition: "output.ext uses 'expected-value', NOT 'wrong-value'"] + [Measurable acceptance criteria] Task 2: [Action-oriented name] path/to/file.ext - [Specific implementation] + path/to/reference.ext + [Specific implementation with concrete values] [Command or check] + + - [Grep-verifiable condition] + [Acceptance criteria] - [What needs deciding] @@ -456,6 +464,39 @@ files_modified: [...] ``` +**Bad: Missing read_first (executor modifies files it hasn't read)** +```xml + + Update database config + src/config/database.ts + + Update the database config to match production settings + +``` + +**Bad: Vague acceptance criteria (not verifiable)** +```xml + + - Config is properly set up + - Database connection works correctly + +``` + +**Good: Concrete with read_first + verifiable criteria** +```xml + + Update database config for connection pooling + src/config/database.ts + src/config/database.ts, .env.example, docker-compose.yml + Add pool configuration: min=2, max=20, idleTimeoutMs=30000. Add SSL config: rejectUnauthorized=true when NODE_ENV=production. Add .env.example entry: DATABASE_POOL_MAX=20. + + - database.ts contains "max: 20" and "idleTimeoutMillis: 30000" + - database.ts contains SSL conditional on NODE_ENV + - .env.example contains DATABASE_POOL_MAX + + +``` + --- ## Guidelines diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index ef3152fc5..96fa61bfc 100644 --- a/get-shit-done/workflows/execute-plan.md +++ b/get-shit-done/workflows/execute-plan.md @@ -136,8 +136,10 @@ Deviations are normal — handle via rules below. 1. Read @context files from prompt 2. Per task: + - **MANDATORY read_first gate:** If the task has a `` field, you MUST read every listed file BEFORE making any edits. This is not optional. Do not skip files because you "already know" what's in them — read them. The read_first files establish ground truth for the task. - `type="auto"`: if `tdd="true"` → TDD execution. Implement with deviation rules + auth gates. Verify done criteria. Commit (see task_commit). Track hash for Summary. - `type="checkpoint:*"`: STOP → checkpoint_protocol → wait for user → continue only after confirmation. + - **MANDATORY acceptance_criteria check:** After completing each task, if it has ``, verify EVERY criterion before moving to the next task. Use grep, file reads, or CLI commands to confirm each criterion. If any criterion fails, fix the implementation before proceeding. Do not skip criteria or mark them as "will verify later". 3. Run `` checks 4. Confirm `` met 5. Document deviations in Summary @@ -226,6 +228,23 @@ Errors: RED doesn't fail → investigate test/existing feature. GREEN doesn't pa See `~/.claude/get-shit-done/references/tdd.md` for structure. + +## Pre-commit Hook Failure Handling + +Your commits may trigger pre-commit hooks. Auto-fix hooks handle themselves transparently — files get fixed and re-staged automatically. + +If a commit is BLOCKED by a hook: + +1. The `git commit` command fails with hook error output +2. Read the error — it tells you exactly which hook and what failed +3. Fix the issue (type error, lint violation, secret leak, etc.) +4. `git add` the fixed files +5. Retry the commit +6. Do NOT use `--no-verify` + +This is normal and expected. Budget 1-2 retry cycles per commit. + + ## Task Commit Protocol diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index bca0b312f..5290af51f 100644 --- a/get-shit-done/workflows/plan-phase.md +++ b/get-shit-done/workflows/plan-phase.md @@ -331,15 +331,47 @@ Planner prompt: Output consumed by /gsd:execute-phase. Plans need: - Frontmatter (wave, depends_on, files_modified, autonomous) -- Tasks in XML format +- Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task) - Verification criteria - must_haves for goal-backward verification + +## Anti-Shallow Execution Rules (MANDATORY) + +Every task MUST include these fields — they are NOT optional: + +1. **``** — Files the executor MUST read before touching anything. Always include: + - The file being modified (so executor sees current state, not assumptions) + - Any "source of truth" file referenced in CONTEXT.md (reference implementations, existing patterns, config files, schemas) + - Any file whose patterns, signatures, types, or conventions must be replicated or respected + +2. **``** — Verifiable conditions that prove the task was done correctly. Rules: + - Every criterion must be checkable with grep, file read, test command, or CLI output + - NEVER use subjective language ("looks correct", "properly configured", "consistent with") + - ALWAYS include exact strings, patterns, values, or command outputs that must be present + - Examples: + - Code: `auth.py contains def verify_token(` / `test_auth.py exits 0` + - Config: `.env.example contains DATABASE_URL=` / `Dockerfile contains HEALTHCHECK` + - Docs: `README.md contains '## Installation'` / `API.md lists all endpoints` + - Infra: `deploy.yml has rollback step` / `docker-compose.yml has healthcheck for db` + +3. **``** — Must include CONCRETE values, not references. Rules: + - NEVER say "align X with Y", "match X to Y", "update to be consistent" without specifying the exact target state + - ALWAYS include the actual values: config keys, function signatures, SQL statements, class names, import paths, env vars, etc. + - If CONTEXT.md has a comparison table or expected values, copy them into the action verbatim + - The executor should be able to complete the task from the action text alone, without needing to read CONTEXT.md or reference files (read_first is for verification, not discovery) + +**Why this matters:** Executor agents work from the plan text. Vague instructions like "update the config to match production" produce shallow one-line changes. Concrete instructions like "add DATABASE_URL=postgresql://... , set POOL_SIZE=20, add REDIS_URL=redis://..." produce complete work. The cost of verbose plans is far less than the cost of re-doing shallow execution. + + - [ ] PLAN.md files created in phase directory - [ ] Each plan has valid frontmatter - [ ] Tasks are specific and actionable +- [ ] Every task has `` with at least the file being modified +- [ ] Every task has `` with grep-verifiable conditions +- [ ] Every `` contains concrete values (no "align X with Y" without specifying what) - [ ] Dependencies correctly identified - [ ] Waves assigned for parallel execution - [ ] must_haves derived from phase goal