[BUG] Explore sub-agents report false findings without verifying via Read/Glob

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Explore-type sub-agents dispatched during a full code review produced findings with a ~38% fully-true rate (8 of 21 claims) and a ~52% true-or-partially-true rate (11 of 21). The remaining 48% of findings were false or impractical.

Failure modes:

• Fabricated findings (5 instances): Sub-agents claimed files lacked test files or documentation blocks without reading or globbing for them. The claimed content was present in the first 15 lines of each file.
• Did not trace call chains (3 instances): Flagged code as buggy based on the function signature alone without checking what callers actually pass. This is particularly problematic for convention-based projects where the same interface type (IDictionary) has different correct method calls depending on the concrete type.
• Ignored documented constraints (3 instances): Recommended parallelization that violates a PS 5.1 compatibility requirement, library replacements for a zero-dependency project, and migrating AI-specific files to developer docs. All three constraints are explicitly documented in CLAUDE.md.

What Should Happen?

1. Sub-agents should verify claims before reporting. If a sub-agent is about to claim "file X has no tests" or "function Y lacks documentation," it should glob or read the file to confirm before including the finding.

1. Sub-agents should trace call chains for convention-dependent code. When flagging a method call as incorrect (e.g., .ContainsKey() vs .Contains()), the sub-agent should trace at least one level of callers to determine what concrete type is actually passed.

1. Sub-agents should apply CLAUDE.md constraints to recommendations. CLAUDE.md contained explicit constraints (PS 5.1 compatibility, no external dependencies, dictionary type conventions) that directly contradicted several findings. Sub-agents should either receive and apply these instructions, or flag when a recommendation may conflict with documented constraints.

1. Findings should distinguish confidence levels. A finding based on reading the code should be presented differently from one based on inference or pattern matching. The current output presents all findings with uniform confidence, making it impossible for the user to triage without re-verifying everything.

Error Messages/Logs

No error messages or stack traces. The issue is the content of sub-agent findings, not a runtime failure.

Steps to Reproduce

1. Set up a PowerShell module codebase (~31 source files, ~7,200 lines) with extensive CLAUDE.md project instructions documenting conventions, constraints, and architecture
2. Ask Claude Code for a full code and documentation review
3. Claude Code dispatches Explore-type sub-agents to analyze different areas of the codebase (defects, test coverage, documentation, architecture, improvements)
4. Each sub-agent returns findings with uniform confidence
5. Manually re-verify each finding in the main conversation by reading the actual code
6. Observe that ~48% of findings are false — sub-agents did not read the files they made claims about, did not trace call chains, or contradicted constraints documented in CLAUDE.md

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

v2.1.81

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

Accuracy summary

| Section | Claims | True | Partially true | False |
| --- | --- | --- | --- | --- |
| Defects | 3 | 1 | 0 | 2 |
| Test coverage gaps | 5 | 3 | 0 | 2 |
| Documentation issues | 5 | 1 | 1 | 3 |
| Scripts and manifest | 0 | 0 | 0 | 0 |
| Architecture | 0 | 0 | 0 | 0 |
| Improvement opportunities | 8 | 3 | 2 | 3 |
| Total | 21 | 8 (38%) | 3 (14%) | 10 (48%) |

• True rate: 8 of 21 (38%)
• True + partially true rate: 11 of 21 (52%)

Detailed findings

Defects (3 claims — 1 true, 0 partially true)

| Sub-agent claim | Verdict | Detail |
| --- | --- | --- |
| .ContainsKey() used on IDictionary parameter is a bug | False | Sub-agent did not trace the call chain. The caller always passes a regular @{} Hashtable, making .ContainsKey() correct. The project has an explicit convention ([ordered]@{} uses .Contains(), @{} uses .ContainsKey()) documented in CLAUDE.md. |
| Regular @{} Hashtable used where [ordered]@{} should be | False | The flagged variable is a boolean tracking set, not a document construction dictionary. Using @{} is intentional and correct. |
| Redundant dual-regex in a string formatting function | True | Cosmetic — two overlapping patterns where one sufficed. Fixed. |

Pattern: Sub-agents flagged code as buggy without reading the calling code or understanding project conventions that were explicitly documented in the instructions they received.

Test coverage gaps (5 claims — 3 true, 0 partially true)

| Sub-agent claim | Verdict | Detail |
| --- | --- | --- |
| Function A has no test file | True | Fixed — created 12 tests. |
| Function B has no test file | True | Fixed — created 13 tests. |
| Tautological assertion in a test file | True | Simplified assertion. |
| Function C has no test file | False | Test file exists. Sub-agent did not check. |
| Function D has no test file | False | Test file exists. Sub-agent did not check. |

Pattern: Two of five "missing test file" claims were wrong because the sub-agent did not glob for existing test files before asserting they were missing.

Documentation issues (5 claims — 1 true, 1 partially true)

| Sub-agent claim | Verdict | Detail |
| --- | --- | --- |
| README.md is incomplete (empty Key Features and Quick Start) | True | Fixed — filled in all sections. |
| Processing log schema is scattered across 3 locations | False | The three locations serve different audiences (AI context, developer docs, cross-conversation memory). Two of the three are always-loaded AI instructions, not user-facing docs. |
| Script A has no comment-based help | False | File has full .SYNOPSIS, .DESCRIPTION, and two .EXAMPLE blocks. Sub-agent did not read the file. |
| Script B has no comment-based help | False | File has .SYNOPSIS and .DESCRIPTION. Sub-agent did not read the file. |
| No cross-version comparison doc | Partially true | The gap exists, but the comparison utility generates this output on demand, and the newer version is still in beta. Low priority. |

Pattern: Two findings were fabricated — the sub-agent claimed files lacked documentation blocks that are present in the first 15 lines of each file.

Scripts and module manifest (0 claims)

Re-review found no issues. The manifest, module loader, and all utility scripts are clean and follow project conventions.

Architecture assessment (0 claims)

Re-review confirmed the architecture is sound. Identified one legitimate refactoring opportunity (extracting ~320 lines from an 852-line orchestrator function) that the sub-agent did not find.

Improvement opportunities (8 claims — 3 true, 2 partially true)

| Sub-agent claim | Verdict | Detail |
| --- | --- | --- |
| Parallelize the main processing loop via Start-Job for 4-8x speedup | Impractical | The loop accumulates shared mutable state (issue lists, page entries, incremental log writes). Parallelizing would require cross-process serialization, eliminating gains. ForEach-Object -Parallel would violate the PS 5.1 compatibility requirement. |
| Batch linter invocations | Partially true | The linter wrapper already accepts directories. Per-file invocation is intentional for incremental log correlation. Minor gain at best. |
| Validate consistency between two derived fields | False | Both fields are derived from the same variable in a single if/elseif/else block. They cannot diverge. |
| Add version declaration to config file | True | Defensive improvement, but the config currently has one entry and the pattern is version-stable. Low risk. |
| Add structure validation test for processing output | True | Legitimate gap — verifying that all entries have expected fields would catch regressions. |
| Extract large functions into sub-helpers | Partially true | Identified the wrong targets. The largest function (877 lines) has clean format-specific branches. The real extraction candidate is a different section of the orchestrator. |
| Migrate .claude/memory/ to docs/ | False | Memory files are AI assistant context (writing style profiles, debugging history), not project documentation. docs/ already has the canonical developer docs. |
| Add dependency graph documentation | True | Useful for onboarding, but 31 files with Verb-Noun naming are largely self-documenting. Low priority. |

Root cause analysis

The false findings cluster into three categories:

1. Did not read the file (5 instances): Claimed files lacked help blocks, test files, or documentation that is present in the first few lines. A single Read or Glob call would have prevented each of these.

1. Did not trace the call chain (3 instances): Flagged code as buggy based on the function signature alone without checking what the callers actually pass. This is particularly problematic for convention-based projects where the same interface type (IDictionary) has different correct method calls depending on the concrete type.

1. Did not account for documented constraints (3 instances): Recommended parallelization that violates PS 5.1 compatibility, suggested library replacements for a zero-dependency project, and proposed migrating AI-specific files to developer docs. CLAUDE.md explicitly documents each of these constraints.

Impact

Even at the more generous ~52% true-or-partially-true rate, nearly half of all findings were wrong. At the ~38% fully-true rate, the user spent more time re-verifying false findings than would have been spent doing the review manually. The sub-agent work was net-negative for the defects and documentation sections, and only net-positive for test coverage (where 3 of 5 findings were real and actionable).