task-framing-claims-need-subagent-grep-verify v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/3acc2ea80f2fcd33.

---
name: task-framing-claims-need-subagent-grep-verify
description: |
  When dispatching a sub-agent (Agent / Task) to WRITE content that cross-
  references existing code paths, explicitly grant + expect grep-driven
  correction of the dispatcher's task-framing claims. Use when:
  (1) your prompt to a sub-agent asserts facts about what an existing
  codebase contains ("X is NOT in v6.1", "Y is already implemented at
  module Z", "feature F handles case G");
  (2) the sub-agent will produce a document, analysis, or design that
  consumers will treat as authoritative;
  (3) the sub-agent has Read/Grep/Glob access to the code being claimed
  about.
  Without an explicit "verify these claims + tag corrections" instruction,
  a sub-agent will either (a) faithfully reproduce the dispatcher's wrong
  claim, or (b) silently substitute its own view without flagging the
  contradiction — both leave the dispatcher with a doc that LOOKS right
  but is stale. Companion to `factcheck-subagent-needs-complete-sources`
  (which covers feeding fact-check agents complete sources) — this skill
  covers the INVERSION: telling write-content agents they can correct
  YOU.
author: Claude Code
version: 1.0.0
date: 2026-05-27
---

# Task-framing claims need sub-agent grep-verify

## Problem

You dispatch a sub-agent to write content (analysis doc, design doc,
implementation plan, code review summary) that needs to cross-reference
existing code paths. To give the sub-agent a head start, you assert facts
in the prompt about what's currently in the codebase:

- "Feature X is NOT in v6.1's training pipeline; the v7 implication is to
  add it as a categorical feature"
- "Module Y already implements caching at line ~120"
- "The current handler doesn't support multipart uploads"

If any of those framing claims are wrong, the sub-agent has two failure
modes — both bad:

1. **Faithful reproduction.** The sub-agent treats your prompt as ground
   truth, doesn't grep to verify, and produces a doc with the wrong
   premise baked in. Downstream readers can't tell the doc was based on
   a faulty premise.

2. **Silent substitution.** The sub-agent greps, finds you wrong, and
   quietly substitutes its own (correct) view — but doesn't flag the
   contradiction. You think your prompt was correct because the doc
   reads sensibly; the discrepancy with your mental model never surfaces.

The fix is ~3 lines of prompt: explicitly grant the sub-agent permission
to verify and correct your task-framing claims, and tell it to TAG any
corrections so the contradiction is visible.

## Context / Trigger Conditions

This skill applies when you're about to launch an Agent / Task subagent
to produce written content AND any of these are true:

- Your prompt contains specific factual claims about what an existing
  codebase contains: "X is not in module Y", "function Z handles case W",
  "feature F is already implemented at file:line N"
- Your prompt provides a numbered list of candidate features / changes /
  implications where each item depends on a "what currently exists" claim
- The sub-agent's output is going to be cited later as authoritative
  ("see analysis doc §3" or "per the design plan, X is needed")
- The sub-agent has Read / Grep / Glob access to the code being claimed
  about (i.e., it CAN verify — it just won't unless told to)

If none of these are true (sub-agent is doing pure exploration, or it has
no code access, or output is throwaway scratch work), this skill doesn't
apply.

## Solution

Add an explicit verify-and-tag block to the sub-agent prompt. Three
mandatory elements:

### 1. Grant correction permission explicitly

State that the sub-agent is *expected* to find errors in your framing:

> "The task-framing claims below describe what I believe v6.1 currently
> contains. I haven't grep-confirmed every one. **Verify each against
> the source before relying on it; if you find a contradiction, proceed
> with the corrected version.**"

Without the explicit grant, even capable sub-agents default to deference.

### 2. Specify the grep target

Don't make the sub-agent hunt for which file to verify against. Name the
canonical source(s):

> "Verify against: `<analytics_pkg>/dataform/v10_training_features_<analytics_pkg>.sqlx`
> + `_feature_common/application_stage.py` + `cr_term_enr_propensity_serve_v6/`.
> Use grep / Read; do not rely on documentation alone."

### 3. Require a visible tag for corrections

Tagging is what surfaces the contradiction back to you:

> "For each finding, tag it `[VERIFIED]` (matches my framing) or
> `[Contradicts task framing]` (you found my claim wrong — proceed with
> your corrected version and explain the discrepancy in 1-2 sentences)
> or `[NEEDS-VERIFICATION]` (you couldn't grep-confirm but the claim is
> plausible). Cite file:line for `[VERIFIED]` items."

The tag is structural feedback. Without it, corrections silently merge
into the doc body and you never learn your framing was wrong.

## Verification

After the sub-agent returns, scan its output for `[Contradicts task
framing]` tags. If any appear:

1. Read the sub-agent's explanation of what your claim got wrong.
2. Either: accept the correction and update any downstream documents
   that referenced the wrong claim; OR push back if you have stronger
   evidence the sub-agent missed something (rare).
3. Update your own mental model. The next time you brief a sub-agent on
   the same topic, your framing should be correct.

If you see no `[Contradicts task framing]` tags and the deliverable feels
suspiciously confident on a topic where you weren't sure: spot-check 2-3
`[VERIFIED]` citations by greping the cited file:line yourself. If those
resolve, trust the rest.

## Example

Bad sub-agent prompt (no correction permission):

```
Write docs/analysis/foo.md covering 8 v7 retrain implications:
1. FAFSA / has_isir_receipt — NOT in v6.1, candidate add
2. Student_Type__c — NOT in v6.1 feature set, candidate add
3. Alien_Status__c — needs derivation, candidate add
... etc
```

Good sub-agent prompt (S217's actual flow):

```
Write docs/analysis/foo.md covering 8 v7 retrain implications.

The 8 findings below come from a fact-check panel against the canonical
sheet. I have NOT grep-confirmed every claim about what v6.1 currently
contains. Verify each against `<analytics_pkg>/dataform/v10_training_
features_<analytics_pkg>.sqlx` + `_feature_common/application_stage.py` +
`cr_term_enr_propensity_serve_v6/`. For each finding, tag it [VERIFIED]
or [Contradicts task framing] or [NEEDS-VERIFICATION] with file:line
evidence. If you find me wrong, proceed with the corrected version and
explain the discrepancy in 1-2 sentences.

1. FAFSA / has_isir_receipt — NOT in v6.1, candidate add
2. Student_Type__c — NOT in v6.1 feature set, candidate add
... etc
```

S217 outcome: sub-agent grep-verified all 8 findings. Two came back
`[Contradicts task framing]`:

> Finding 2 (Student_Type__c): "NOT in v6.1" was wrong — `app_student_type`
> IS already a feature in v6.1 at lines 226/769/1039. The v7 implication
> is vocabulary pinning post-2026-04-17 model promotion, NOT adding.

> Finding 5 (Alien_Status__c): "needs derivation" implied absence — it
> IS already pulled at line 585 into `enrollment_salesforce_features`
> and surfaced at line 1267. The v7 question is grain semantics + lead-
> stage proxy quality, not whether to add.

Without the correction-permission grant, both findings would have shipped
as "add this feature to v7" — wrong recommendation, would have shown up
as embarrassing in v7 design review.

## Notes

**Why explicit grant is needed.** Modern sub-agents are trained to be
helpful and to follow dispatcher instructions. When the dispatcher's
framing is factually wrong but plausibly stated, the default is to
faithfully reproduce. The explicit "verify + correct + tag" instruction
overrides the default-deference.

**Why tagging matters more than correcting.** Without tags, a sub-agent
that silently corrects your framing produces a doc that LOOKS like it
agreed with your prompt — but in reality your prompt was wrong AND you
never learned it was wrong. The next session you'll repeat the same wrong
framing. Tags break the cycle.

**Where this is most valuable.** High-leverage analysis docs, design
plans, code-review summaries, anything that downstream consumers will
cite as authoritative. Lower-value where the sub-agent is doing pure
exploration with no claim-to-fact.

**Related failure modes that this skill does NOT cover:**

- `factcheck-subagent-needs-complete-sources` — about giving fact-check
  sub-agents complete sources (not the inversion this skill covers)
- `subagent-pre-existing-misattribution` — about attributing pre-existing
  issues to sub-agent work (different blame-direction)
- `agent-review-panel-stale-cite-verification` — about reviewers verifying
  their cites are not stale (different scope: reviewer self-check, not
  dispatcher claim correction)

**Skill activation heuristic.** Before writing an Agent / Task prompt
that includes "X is not in Y" or "Z is already implemented at W" type
claims, ask: would I bet my next deliverable that this is currently
true in the codebase? If no — add the verify-and-tag block.

## References

- S217 worked example: PR #963 (`the-project-repo`),
  `docs/analysis/2026-05-27-s216-findings-for-v7.md` — sub-agent
  caught 2 of 8 task-framing errors via grep-verify against
  `v10_training_features_<analytics_pkg>.sqlx`.
- Companion skill: `factcheck-subagent-needs-complete-sources` (covers
  feeding fact-check agents complete sources — different direction)
- Project lesson: `~/.claude/projects/.../memory/lessons.md` #129 (the
  S217 origin write-up)