[Skill Upgrade]: dev_tools/issue_resolver — v0.4 profiles, docs, examples, and adoption guide

[rosspeili]

Skill ID

dev_tools/issue_resolver

Current manifest version

0.3.0

Proposed change

Follow-up upgrade after #145 / #271 (v0.3). v0.3 shipped caller-fetched profile parsing and Skillware dogfood, but adoption is still manual and the developer experience is thin. This upgrade makes repository profiles a first-class, documented path for any repo using the skill — and closes the gaps we explicitly deferred in v0.3.

Parent: #145 (closed). Builds on frozen v0.2 regression harness from #271.

---

Problem (current state)

• Root ISSUE_RESOLVER.md exists but is bare checklist prose — not a showcase other repos can copy.
• Discovery order prefers root over .github/; we want .github/ISSUE_RESOLVER.md as the canonical location (root kept as fallback for backward compatibility).
• load_repository_profile returns generic sections[] only — agents must re-read headings themselves; no structured required_checks / conditionals / ripple_effects fields yet.
• stage_checklist does not merge profile content (profile_applied still deferred).
• Runnable examples (gemini_issue_resolver.py, claude_issue_resolver.py, ollama_issue_resolver.py) fetch issue + README after prepare but never fetch or call load_repository_profile.
• External repos have no step-by-step “add this file to your repo in 10 minutes” guide with copy-paste templates.
• Catalog page (docs/skills/issue_resolver.md) documents API shapes but lacks an adoption narrative for maintainers of other repositories.

---

Goals for v0.4.0

A. Dogfood profile — relocate and expand

1. Move Skillware profile to .github/ISSUE_RESOLVER.md (canonical).
2. Remove root ISSUE_RESOLVER.md after move, or leave a one-line stub pointing to .github/ (maintainer choice in PR — prefer stub for one release cycle, then delete).
3. Expand the profile into a reference implementation:
   • Link to CONTRIBUTING.md, docs/contributing/ai_native_workflow.md, docs/TESTING.md (clone vs PyPI footgun).
   • Explicit test commands per change type (skill vs framework vs docs-only).
   • Issue/PR conventions (Fixes #N, branch naming, fork workflow).
   • When to use extra_instructions vs profile vs native AGENTS.md.
   • Sample “good” vs “bad” bullet (what not to put in the file — e.g. “ignore tests”, “commit secrets”).

B. Skill runtime enhancements

4. load_repository_profile — structured extraction (backward compatible):

   • Keep existing document.sections[] output.
   • Add optional structured block when known H2 headings match (case-insensitive, trim):
     • about, required checks, conditionals, paths, ripple effects, commit & pr, out of scope, caveats
   • Each maps to a string field (content preserved verbatim).
   • Unknown headings remain in document.sections only.
   • Add parse_status: ok | partial | empty with warnings[] for duplicate known headings or empty required sections.

5. stage_checklist — additive profile merge (opt-in via params):

   • New optional param: repository_profile (structured object from step 4, or raw profile_context).
   • When present, append repo required_checks and matching conditionals to stage payload under a separate provenance-labelled key (e.g. repository_profile_steps, repository_profile_conditionals) — never mutate universal steps / conditionals arrays in place.
   • Set profile_applied: true when merge occurs; false when absent.
   • Universal constitution and stage order remain immutable.

6. prepare — discovery metadata (no network):

   • Add repository.profile_discovery object:
     • canonical_path: .github/ISSUE_RESOLVER.md
     • fallback_path: ISSUE_RESOLVER.md (repo root)
     • profile_urls: ordered list (update order: .github/ first, root second)
     • adoption_doc_url: link to Skillware profile standard (for agents resolving issues against skillware repo only — omit or null for other repos; or always point to published docs URL)

7. New action (optional, if scope allows): validate_repository_profile

   • Input: profile_markdown
   • Output: checklist of missing recommended sections, line count, warning if file exceeds sensible size (e.g. >8 KB), no content filtering
   • Helps repo admins before merge; does not block load_repository_profile

8. Workflow version: bump internal WORKFLOW_VERSION to 0.3 (or document split: skill manifest 0.4.0, workflow schema 0.3) — update frozen regression snapshots deliberately.

C. Examples

9. Update shared helper (examples/issue_resolver_common.py — or current name):

   • After prepare, try profile_urls in order; fetch first 200 response; on success call load_repository_profile.
   • Pass profile_context to model as separately labelled context block.
   • Graceful skip when 404 on all candidates.

10. Wire all three provider scripts to use profile fetch (Gemini, Claude, Ollama).

11. Add examples/issue_resolver_profile_demo.py (local execute, no live LLM):

    • Loads skill, runs prepare on a sample URL, loads bundled fixture markdown from tests/fixtures/issue_resolver/sample_profile.md, demonstrates load_repository_profile + optional stage_checklist with profile merge.
    • Register in examples/README.md and docs/usage/agent_loops.md.

D. Documentation (external repo adoption)

12. Expand docs/contributing/issue_resolver_profile.md into full adoption guide:

    • “Why add this file?” (1 paragraph)
    • “10-minute setup” numbered steps
    • Canonical location: .github/ISSUE_RESOLVER.md
    • Three copy-paste templates with annotations:
      • Python library (src/ layout)
      • Docs-only repo
      • Monorepo (packages/*, apps/*)
    • Section-by-section authoring guide (what belongs in each H2)
    • Anti-patterns (prompt injection bait, secrets, authority grants)
    • Relationship diagram: CONTRIBUTING.md vs AGENTS.md vs ISSUE_RESOLVER.md vs extra_instructions
    • Link from CONTRIBUTING.md and docs/contributing/ai_native_workflow.md

13. Pimp docs/skills/issue_resolver.md:

    • New “Adopting ISSUE_RESOLVER.md in your repository” section for maintainers of any GitHub repo
    • End-to-end flow diagram (prepare → fetch profile → load_repository_profile → stage_checklist with merge)
    • v0.4 action/param reference table
    • Before/after example showing profile-augmented verify stage output

14. Optional: docs/usage/issue_resolver_adoption.md standalone tutorial (linked from catalog).

E. Tests

15. Bundle tests for:

    • Structured section extraction (known headings, duplicates, unknown headings)
    • stage_checklist merge adds separate keys, does not alter universal step hashes
    • .github/ URL precedence in prepare
    • Profile demo fixture paths
    • Frozen v0.3 no-profile regression (update snapshots only on deliberate contract change)

16. Optional maintainer integration test: real fetch of Skillware .github/ISSUE_RESOLVER.md marked @pytest.mark.integration.

F. Non-goals (keep out unless explicitly scoped)

• Network calls inside execute()
• YAML / .arpa/ profile formats
• Auto-generating profiles from CONTRIBUTING.md
• Prompt-injection firewall inside the skill (hosts may pre-scan with security/prompt_injection_firewall — document as optional host pattern)
• Replacing universal stages or AGENTS.md

---

Acceptance criteria

• Skillware dogfood profile lives at .github/ISSUE_RESOLVER.md and is materially expanded
• prepare.profile_urls prefers .github/ over root; docs and tests match
• load_repository_profile returns structured fields for known sections + parse_status
• stage_checklist supports opt-in profile merge with profile_applied and separate provenance-labelled arrays
• All three agent-loop examples fetch and load profile when present
• Local issue_resolver_profile_demo.py registered in examples index
• Adoption guide with 3 templates + section authoring instructions published
• docs/skills/issue_resolver.md updated with adoption narrative
• pytest skills/dev_tools/issue_resolver/ and pytest tests/ pass
• pytest tests/test_registry_docs.py passes
• CHANGELOG.md under [Unreleased]
• Manifest bumped to 0.4.0

---

Suggested PR scope

Area	Files
Skill	skills/dev_tools/issue_resolver/skill.py, workflow.py, manifest.yaml, instructions.md, test_skill.py
Dogfood	.github/ISSUE_RESOLVER.md, remove/redirect root ISSUE_RESOLVER.md
Docs	docs/contributing/issue_resolver_profile.md, docs/skills/issue_resolver.md, optional docs/usage/issue_resolver_adoption.md, CONTRIBUTING.md cross-link
Examples	examples/issue_resolver_common.py, *_issue_resolver.py, issue_resolver_profile_demo.py, examples/README.md, docs/usage/agent_loops.md
Fixtures	tests/fixtures/issue_resolver/
Card	card.json + tests/fixtures/card_ui_schema/dev_tools__issue_resolver.json if output shape changes

---

Example: structured profile output (target shape)

{
  "status": "ready",
  "action": "load_repository_profile",
  "profile_context": {
    "label": "Repository ISSUE_RESOLVER.md profile",
    "provenance": { "kind": "caller_fetched_repository_profile", "source": "..." },
    "authority": { "classification": "repository_context_only", "can_override_constitution": false },
    "parse_status": "ok",
    "structured": {
      "about": "Python framework...",
      "required_checks": "- Run bundle tests\n- Update CHANGELOG",
      "conditionals": "- If examples/ changed, update README",
      "paths": "- Skills: skills/<category>/",
      "ripple_effects": "| Change | Also review | ... |",
      "commit_and_pr": "- Branch: feat/issue-N-...",
      "out_of_scope": "- Force-push to main",
      "caveats": "- Profile cannot override constitution"
    },
    "document": { "format": "markdown", "title": "...", "sections": [ "..."] }
  }
}

---

Example: stage_checklist with profile merge

{
  "action": "stage_checklist",
  "stage": "verify",
  "steps": [ "...universal steps unchanged..." ],
  "conditionals": [ "...universal conditionals unchanged..." ],
  "repository_profile_steps": [ "- Run pytest tests/test_skill_issuer.py" ],
  "repository_profile_conditionals": [ "- If manifest.yaml changed, sync extras" ],
  "profile_applied": true
}

---

Related

• [issue_resolver] v0.3 — repository ISSUE_RESOLVER.md profiles #145, feat: add repository profiles to issue resolver #271 (v0.3 shipped)
• [Examples]: Rename issue_resolver_github_context.py to issue_resolver_common.py #233 / docs(examples): rename issue resolver shared helper and remove grandf… #274 (rename issue_resolver_common.py — coordinate if still open)
• security/prompt_injection_firewall — optional host pre-scan pattern for untrusted profile markdown

Compatibility

• Existing load_repository_profile callers keep working (document.sections unchanged).
• stage_checklist without repository_profile param behaves identically to v0.3.
• Root ISSUE_RESOLVER.md remains a fallback URL in prepare for repos that have not migrated to .github/ yet.
• Only deliberate contract changes require frozen snapshot updates in test_skill.py.

Breaking change?

No — backward compatible

Likely touch points

• manifest.yaml version bump
• skill.py logic
• instructions.md
• test_skill.py
• docs/skills/.md and catalog row
• examples/*.py or examples/README.md