Skip to content

propose: java-codebase-explore agent skill#77

Merged
HumanBean17 merged 1 commit into
masterfrom
propose/exploration-skill
May 11, 2026
Merged

propose: java-codebase-explore agent skill#77
HumanBean17 merged 1 commit into
masterfrom
propose/exploration-skill

Conversation

@HumanBean17

@HumanBean17 HumanBean17 commented May 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Draft propose for a new standalone agent skill, java-codebase-explore.

Scope of this PR (PR-EXPLORE-1): propose doc only — propose/EXPLORATION-SKILL-PROPOSE.md. The skill file (docs/skills/java-codebase-explore.md), the packaged .zip, and the build script land in the follow-up implementation PR (PR-EXPLORE-2) once this propose is locked.

Frame. docs/AGENT-GUIDE.md is a tool operating manual — it teaches agents how to drive the four MCP tools without breaking them. It does not teach exploration strategy at the system level: when to use MCP vs fall back to rg/file reads/CLI, how to read staleness and confidence, what missions to run in what order. This propose ships that strategy guide as a standalone agent skill, distributable as markdown + a Perplexity-format .zip from this repo.

Companion: propose/AGENT-GUIDE-SURGICAL-PATCHES-PROPOSE.md (separate branch propose/agent-guide-patches) — three small patches to AGENT-GUIDE.md that ship even if this skill never does.

TL;DR

  • Add docs/skills/java-codebase-explore.md + Perplexity-format .zip generated by scripts/build-explore-skill.sh. Other platforms (Claude Code, Cursor) deferred to v2 until a real consumer needs them.
  • Standalone: operable without AGENT-GUIDE.md in context. Cheat sheet appendix inlines 4 tools, 9 edges, 3 node kinds — nothing more.
  • 6 named missions (count locked in §7): understand a feature, plan a change, onboard, trace cross-service flow, prepare to write a propose doc, debug a symptom.
  • Anti-capabilities ("what this MCP cannot see") are a first-class section, not a footnote.
  • Confidence + staleness rules: file wins over MCP; low cross-service confidence on edge.attrs is a resolver gap signal.
  • Migration shape: 2 PRs — this propose merge → ship the skill. No code, no schema, no ontology bump.

Revision in response to review (force-push)

  • §2, §3, §7 now all say 6 missions (was "5–7" in §2 / §3.2.4).
  • edge.attributes.* → edge.attrs.* throughout (matches the Edge Pydantic model in mcp_v2.py).
  • §1 / §3.1 / §8 zip-scope reconciled — Perplexity format only is the single source of truth, declared in §8 risk row and referenced from §1 / §3.1.
  • cursor-pr-review labelled as an example external skill, not shipped from this repo.
  • §6 PR-EXPLORE-2 acceptance check now exercises UC2 + UC6 as smoke cases.
  • §7 decision PR-A1: Route schema + literal extractor (B2a) #5 footnotes CLI-SCENARIOS §6 as the cardinal-number-locking precedent.

Key design decisions (locked in §7)

  • Skill name: java-codebase-explore (brand-aligned with java-codebase-rag).
  • Mission count locked at 6. Adding a 7th requires a propose (mirrors CLI-SCENARIOS §6 discipline).
  • Section order locked: pre-flight → seams → missions → fallbacks → anti-capabilities → confidence/staleness → anti-patterns → cheat sheet.
  • Cheat sheet is the only place ontology strings appear in this skill.
  • Activation phrases are intent-scoped (see §3.5).

Use-case re-walk

16 realistic exploration intents (UC1–UC16) walked through the proposed surface. Every intent maps to either a mission (13 cases), a meta-skill section (1 case), or an explicit fallback rule (3 cases). No surface revisions triggered. See §4.

Ready for review.

@HumanBean17

HumanBean17 commented May 11, 2026

Copy link
Copy Markdown
Owner Author

Review (design-only PR)

Scope clarity: This PR only adds propose/EXPLORATION-SKILL-PROPOSE.md, which matches PR-EXPLORE-1. Consider one line at the top of the PR body that skill files / zip / script land in PR-EXPLORE-2 so reviewers do not expect them here.

Strengths: Clear split AGENT-GUIDE (how to call tools) vs exploration skill (when/why, fallbacks, stopping rules). Anti-capabilities and staleness match the repo (test paths excluded; increment vs Kuzu). UC table filter examples align with NodeFilter in mcp_v2.py. Two-PR migration is proportionate.

Fix before / in PR-EXPLORE-2:

  • edge.attributes vs wire JSON: UC14 and Appendix A say edge.attributes.confidence. The Edge model uses attrs. For standalone skill text, align with the payload or say both (attributes / attrs).
  • §2 vs §3: §2 still says "5–7" missions; §3/§7 lock at 6 — tighten §2.
  • cursor-pr-review: Label as an example external skill so readers do not assume it ships from this repo.
  • Zip scope: §8 says Perplexity-only v1 zip; §3.1 lists multiple platforms — reconcile in one place.

Optional: Footnote link to propose/completed/CLI-SCENARIOS-PROPOSE.md for the §6 discipline reference; note UC10 as a second smoke case alongside UC6 acceptance.

Verdict: Good to merge as propose lock once the small doc inconsistencies are fixed; ship skill + build script in follow-up PR with appendices matching actual MCP field names.

@HumanBean17
propose: java-codebase-explore agent skill
45cca28 
Adds propose/EXPLORATION-SKILL-PROPOSE.md. The actual skill file
(docs/skills/java-codebase-explore.md), the build script, and the
generated .zip land in the follow-up implementation PR (PR-EXPLORE-2)
once this propose is locked.
@HumanBean17 HumanBean17 force-pushed the propose/exploration-skill branch from b4aebdb to 45cca28 Compare May 11, 2026 17:58
@HumanBean17

HumanBean17 commented May 11, 2026

Copy link
Copy Markdown
Owner Author

Thanks — addressed in force-push (b4aebdb → 45cca28). Per-point:

  • edge.attrs vs wire JSON. Confirmed against mcp_v2.py line 125 (attrs: dict[str, Any]). Replaced every edge.attributes.* with edge.attrs.* / attrs.confidence / attrs.strategy / attrs.match across §3.2.7, §3.4 anti-capabilities row, §4 UC14, and Appendix A.
  • §2 vs §3 mission count. §2 now says 6 named missions (count locked in §7) — single source of truth is §7 decision PR-A1: Route schema + literal extractor (B2a) #5.
  • cursor-pr-review framing. §3.5 when_not_to_load row and §8 over-activation risk row both now label it explicitly as an example external skill in Dmitriy's user-skill library, not shipped from this repo.
  • Zip scope. Reconciled at one source of truth: §8 risk row says "Perplexity format only — primary consumer; Claude Code / Cursor variants deferred until a real downstream consumer needs them." §1 TL;DR and §3.1 now both align with that.
  • Optional — CLI-SCENARIOS §6 footnote. §7 decision PR-A1: Route schema + literal extractor (B2a) #5 now footnotes propose/completed/CLI-SCENARIOS-PROPOSE.md §6 as the cardinal-number-locking precedent.
  • Optional — UC10 smoke case. §6 PR-EXPLORE-2 acceptance check now exercises UC2 + UC6 (UC6 picked over UC10 since it exercises a richer fallback-rule path; happy to swap to UC10 if you'd prefer).
  • Scope clarification. PR body now leads with a > Scope of this PR (PR-EXPLORE-1) blockquote that names PR-EXPLORE-2 as the home for the skill file / zip / build script.

PR body refreshed with the revision summary. Ready for a re-read when you have a moment.

@HumanBean17 HumanBean17 mentioned this pull request May 11, 2026
Merged
@HumanBean17 HumanBean17 marked this pull request as ready for review May 11, 2026 18:00
@HumanBean17 HumanBean17 merged commit bac98a6 into master May 11, 2026
This was referenced May 11, 2026
Merged
Merged
Merged
@HumanBean17 HumanBean17 deleted the propose/exploration-skill branch May 23, 2026 18:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@HumanBean17