[issue_resolver] v0.3 — repository ISSUE_RESOLVER.md profiles

[rosspeili]

Skill Name

dev_tools/issue_resolver

What should this skill do?

What needs to be fixed?

dev_tools/issue_resolver v0.2 (shipped in 0.3.3, #143) provides a universal GitHub issue workflow: sequential stages, conditional checks inferred from README / CI / tree, and commit gates. That works on any repo, but it cannot know project-specific nuance unless the agent discovers it slowly or the operator injects extra_instructions every time.

Goal for v0.3: let any repository opt in by dropping a root-level profile file — ISSUE_RESOLVER.md — so the skill immediately understands local conventions, caveats, required checks, and ripple-effect hints. Universal stages stay; the profile extends them.

---

Why this matters (any repo using issue_resolver)

Without profile	With ISSUE_RESOLVER.md at repo root
Agent infers rules from README, CONTRIBUTING, CI	Maintainer declares rules once, in agent-oriented form
Skillware-specific or team-specific gates live in prompts	Same skill works seamlessly on Skillware, a Python lib, a monorepo, or a docs-only repo
Easy to miss changelog, fork workflow, test scope	Explicit required checks per stage (verify, commit, PR)
Ripple effects guessed from tree	Profile can name nested paths, doc ripples, catalog updates

Drop-in story: clone any repo → open an issue URL → agent calls prepare → skill discovers ISSUE_RESOLVER.md → stage checklists merge universal + repo rules → resolution follows this project's expectations without hardcoding paths in the skill.

Builds on v0.2 (workflow.py, stage_checklist, validate_commit_message). Does not replace CONTRIBUTING.md; complements it for agents.

---

Proposed standard: ISSUE_RESOLVER.md

Location (discover in order):

1. Repository root: ISSUE_RESOLVER.md
2. Optional fallback: .github/ISSUE_RESOLVER.md

Purpose: short, checklist-oriented markdown the skill parses (or returns as structured payload) during discover_repository.

Suggested sections (minimal v0.3):

• About — one paragraph: stack, contribution model (fork vs direct), release cadence
• Required checks — hard gates (e.g. must update CHANGELOG under [Unreleased], must run subset of tests)
• Conditionals — extra If X then Y rules beyond universal workflow
• Paths — where source, tests, docs, examples, CI config live (including nested layouts)
• Ripple effects — when file X changes, also check Y (e.g. skill change → catalog + examples index)
• Commit & PR — branch naming, remote, message format, template path
• Out of scope — what agents must not do in this repo
• Caveats — security, co-author policy, version bumps, private deps

Example (Skillware-shaped, illustrative):

# Issue resolver profile — Skillware

## About
Python skill registry. Contributors use fork + PR. User-facing changes go in CHANGELOG `[Unreleased]`.

## Required checks
- Docs-only or skill PRs: update `CHANGELOG.md` under `[Unreleased]`
- New/changed skill: update `docs/skills/<name>.md`, `docs/skills/README.md`, and `examples/README.md` if adding a runnable script
- Run relevant tests: `py -3.13 -m pytest skills/<category>/<skill>/test_skill.py -q`

## Conditionals
- If the change touches `manifest.yaml`, ensure `issuer` is real and `card.json` matches
- If adding an example under `examples/`, register it in `examples/README.md` and `docs/usage/agent_loops.md`
- If bumping package version, update `pyproject.toml` and CHANGELOG release section together

## Paths
- Skills: `skills/<category>/<skill_name>/`
- Skill docs: `docs/skills/`
- Runnable examples: `examples/`
- CI: `.github/workflows/`

## Ripple effects
| Touch | Also review |
|-------|-------------|
| `skills/*/` | `docs/skills/*.md`, `tests/test_skill_issuer.py` if issuer rules apply |
| `examples/*.py` | `examples/README.md`, skill catalog Usage Examples |
| `skillware/core/loader.py` | all provider adapter docs under `docs/usage/` |

## Commit & PR
- Branch: `feat/issue-<N>-short-desc`
- Push to `fork`, PR against `ARPAHLS/main`
- No AI `Co-authored-by` unless maintainer allows

## Out of scope
- Force-push to shared default branches
- Skip hooks or commit secrets

## Caveats
- Skill logic stays deterministic; profile guides the **agent**, not `execute()` network/git

Other repos would replace paths and checks with their own (Node monorepo, Terraform, docs site, etc.).

---

Skill changes (v0.3)

Version: dev_tools/issue_resolver → 0.3.0

Area	Change
discover_repository	Fetch profile URL(s); include in prepare payload or new repository.profile_url
New action (optional)	load_repository_profile — returns parsed/normalized profile + merge hints for stages
stage_checklist	When profile present, append repo required checks and conditionals to stage payload (never remove universal gates)
workflow_overview	Replace future_profiles_note with active profile support
instructions.md	Document profile discovery and merge rules
skill.py	Deterministic fetch is still agent-side OR optional read-only raw URL in payload (align with v0.2: skill does not call GitHub unless we explicitly decide one raw URL list in prepare)

Merge rule: universal workflow wins on safety/constitution; profile adds constraints only.

Backward compatible: no file → identical to v0.2 behavior.

---

Documentation & tutorials (deliverables)

• docs/standards/ISSUE_RESOLVER.md (or docs/contributing/issue_resolver_profile.md) — normative spec + examples for Python, docs-only, monorepo layouts
• docs/skills/issue_resolver.md — v0.3 actions, profile merge behavior
• Tutorial: “Add ISSUE_RESOLVER.md to your repo in 10 minutes”
• Dogfood: add root ISSUE_RESOLVER.md to this repository as reference implementation
• Examples: optional note in gemini_issue_resolver.py / docs when sample repo has a profile

Topics to cover in docs:

• Nested paths and monorepos (packages/foo/, apps/web/)
• File-type ripples (.md, yaml, py, CI workflows)
• When to use profile vs CONTRIBUTING vs extra_instructions
• Private repos + GITHUB_TOKEN

---

Acceptance criteria

• Skill discovers profile path(s) during repository discovery and exposes them to the agent
• stage_checklist merges repo profile checks/conditionals when profile content is available
• No profile → v0.2 behavior unchanged (regression tests)
• Spec doc published with at least two example profiles (e.g. Skillware + minimal generic library)
• Skillware repo includes its own root ISSUE_RESOLVER.md
• docs/skills/issue_resolver.md and CHANGELOG updated
• test_skill.py covers profile merge logic (fixtures, no live GitHub required)

---

Out of scope (v0.3)

• JSON Schema / YAML profile format (markdown-first only)
• Skill calling GitHub API inside execute() (keep agent-driven fetch unless explicitly revised)
• Auto-generating profiles from CONTRIBUTING.md
• Replacing universal stages with profile-only workflow

---

Suggested PR scope

• skills/dev_tools/issue_resolver/ — workflow.py, skill.py, manifest.yaml, instructions.md, tests
• ISSUE_RESOLVER.md (repo root, dogfood)
• docs/standards/ or docs/contributing/ — profile standard + tutorial
• docs/skills/issue_resolver.md, CHANGELOG.md

---

Related

• Builds on [issue_resolver]: v0.2, full agent workflow through verify, commit, and PR #143 (issue_resolver v0.2), [Examples]: Add runnable agent-loop example for dev_tools/issue_resolver #118 (runnable examples)
• Release: minor skill bump in a future package release (e.g. 0.3.4 or 0.4.0 per semver policy)

Affected Page

skills/dev_tools/issue_resolver/, new ISSUE_RESOLVER.md standard docs, skill catalog

Ideal Inputs & Outputs

Input (prepare — unchanged):
{"action": "prepare", "issue_url": "https://github.com/owner/repo/issues/42"}

Output (prepare — v0.3 adds profile URLs):
{"status": "ready", "action": "prepare", "repository": {"profile_urls": ["https://raw.githubusercontent.com/owner/repo/HEAD/ISSUE_RESOLVER.md", "https://raw.githubusercontent.com/owner/repo/HEAD/.github/ISSUE_RESOLVER.md"], "profile_found": true}, "issue": {"url": "...", "api_url": "..."}}

Input (stage_checklist with profile context available):
{"action": "stage_checklist", "stage": "verify", "repository_profile": {"required_checks": ["Update CHANGELOG under [Unreleased] if user-visible"], "conditionals": ["If examples/ changed, update examples/README.md"]}}

Output (stage_checklist — merged universal + repo):
{"status": "ready", "action": "stage_checklist", "stage": "verify", "steps": ["..."], "conditionals": ["...universal...", "...from ISSUE_RESOLVER.md..."], "profile_applied": true}

Input (no profile in repo):
{"action": "stage_checklist", "stage": "plan"}

Output (no profile — identical to v0.2):
{"status": "ready", "action": "stage_checklist", "stage": "plan", "profile_applied": false}

Targeted Models (if applicable)

Model Agnostic (All)