Skip to content

Fan out issue grounding as parallel Explore agents in webjs-file-issue #1162

Description

@vivek7405

Problem

webjs-file-issue step 1 mandates grounding the issue body in the real codebase (files/functions with real paths, landmines, invariants, test and doc surfaces) before filing, and it is the step the skill itself says "gets skipped". Part of why it gets skipped is cost: done inline and serially, it is four unrelated hunts through the repo that block the conversation. All four hunts are independent reads, which is exactly the fan-out shape the Explore agent exists for, and the skill never mentions it.

Design / approach

Amend step 1 of .claude/skills/webjs-file-issue/SKILL.md: for a non-trivial issue, fan the grounding out as parallel read-only Explore agents in ONE message, one per concern (where-to-edit paths, landmines/prior incidents via git log and issue search, invariants from AGENTS.md, test+doc surfaces), then synthesize their returns into the Implementation-notes section. Keep the cold-start test as the gate on the RESULT: the fan-out is a means, and a body that fails the cold-start test is unready no matter how it was researched. For a small, well-understood issue, inline grounding stays fine, so phrase it as the default for anything touching more than one area, not a mandate.

Implementation notes (for the implementing agent)

  • Where to edit: .claude/skills/webjs-file-issue/SKILL.md, step 1 (grep "Ground the body BEFORE you create anything", near L31).
  • Landmine: Explore agents are read-only and cannot Write, which is the point; do NOT suggest general-purpose agents here, since a grounding helper that edits the repo mid-filing is a hazard. Name the Explore agent type explicitly.
  • Landmine: the mirrored copy at ~/.claude/skills/webjs-file-issue/SKILL.md must be updated in the same change (diff -q afterwards); this pair has drifted before (see Never let a dead review subagent stall or downgrade the loop #1158's mirroring requirement for the sibling skill).
  • Invariants: AGENTS.md invariant 11 on new prose.
  • Tests / docs: node --test test/hooks/route-skills.test.mjs still passes; no other surface.

Acceptance criteria

  • Step 1 offers a parallel Explore fan-out (one message, one agent per grounding concern) as the default for multi-area issues
  • The Explore agent type is named and its read-only nature stated as the reason
  • The cold-start test remains the acceptance gate on the body
  • Inline grounding remains sanctioned for small single-area issues
  • Both skill copies identical (diff -q)

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions