investigate-contract
Skill459 starsChanged 3 months agoMITView on GitHub
Read-only guarantee + interactive-vs-autonomous (--auto) behavior for investigate modes. Internal helper invoked by the investigate mode of feat / fix — not meant to be run on its own.
Files
Applies whenever a skill runs with --investigate. The domain-specific output (a plan, or a bug triage) and any labeling live in the calling skill; this is the shared contract.
Read-only (enforce yourself)
Investigate mode is strictly read-only: never edit code, never create a branch, never commit. Nothing at the tool level blocks you here, so hold the line yourself. The only writes you make are the GitHub-issue comment (gh issue comment, via the save-plan-to-github skill) and, in autonomous mode, a label the calling skill may add (gh issue edit --add-label). Other hard limits (no force-push, no destructive shell) are enforced by .claude/settings.json deny/ask rules — if a tool call is blocked, do not work around it.
Interactive vs autonomous
--investigate is interactive by default; --investigate --auto is autonomous. The analysis is identical — only the human-in-the-loop differs:
Interactive (--investigate) | Autonomous (--investigate --auto) | |
| Questions | May ask 1-2 targeted questions when a material ambiguity changes the output | Never ask — record the assumption and proceed |
| Use case | While the user is at their machine | Unattended batch (e.g. nightly) |
Record assumptions instead of blocking
When the issue is underspecified, don't stall. Interactive: ask only the question(s) that materially change the output; for everything minor, state the assumption explicitly in the posted block (under an "Assumptions" heading) and proceed. Autonomous: never ask — always record the assumption and continue. A reader seeing your assumptions is far more useful than a half-done investigation waiting on input.
Review before posting (interactive only)
The posted block is the deliverable — but in interactive mode the user is sitting with you, so let them shape it before it lands on the issue. Draft the plan, present it in chat, fold in their edits, and post the comment only once they approve. Posting an unreviewed plan and asking for validation after it's already on the issue is backwards when a human is right there to catch a wrong assumption or a missing constraint first.
For the in-chat review, show every section expanded — don't wrap sections in <details> collapsibles (those hide content the user wants to see now). Keep the tables/bullets as-is. Assemble the final comment (with <details> around the long sections) only at the moment you post it, after approval.
Autonomous (--auto) is the exception: there's no human to ask, so post directly — the gh issue comment call is the deliverable and the only write. Never block an unattended run waiting on approval.
Other versions1 project uses a version of this.
Word for word · 1
- Akylas/OSS-DocumentScanner★ 2.6k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- branch-checkSkill
- commitSkill
- writing-great-skillsSkill
- documentSkill
- featSkill
- fixSkill
- grill-meSkill
- open-prSkill
- save-plan-to-githubSkill
- understand-projectSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.