[KatalKavya96]

Summary

• Add a first-run welcome guide for the Issue Management family, covering all eight skills so newcomers can discover triage, deduplication, reproduction, reassessment, fix drafting, stale-issue handling, and reporting workflows through natural-language requests.
• Explain skill-specific configuration requirements and safety boundaries, including explicit confirmation for tracker comments and closures, additional confirmation for stale closures, and opt-in draft PR creation.
• Link the guide from docs/issue-management/README.md, add first-run regression tests and a preflight-floor evaluation fixture, regenerate affected welcome reports, and update evaluation case counts.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other: Setup-preflight welcome guide and evaluation fixture

Test plan

• prek run --all-files passes
• For Python packages touched: uv run pytest / ruff check / mypy passes
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other:
  • Setup-preflight welcome regression tests passed through the workspace test suite.
  • Preflight fixture reports regenerated and verified by the render-preflight-fixtures hook.
  • Welcome guide rendering and the 70-line limit are covered by regression tests.
  • git diff --check passed.
  • Repository-wide Ruff, mypy, pytest, documentation synchronization, and skill validation passed.

RFC-AI-0004 compliance

• HITL — documents explicit maintainer confirmation before tracker mutations and the separate approval required for stale-issue closure.
• Sandbox — no new unrestricted host access or runtime permissions introduced.
• Vendor neutrality — existing tracker and project configuration conventions are preserved.
• Conversational + correctable — natural-language workflow examples and customization guidance are included.
• Write-access discipline — posting, closing, and draft PR creation remain explicitly confirmed actions.
• Privacy LLM — not affected by this change.

Linked issues

Closes #1656

Refs #1654

Notes for reviewers (optional)

• Follows the existing first-run welcome-guide pattern established in feat(setup): first-run welcome guides, general and for the security skills #1653 and feat(setup): first-run welcome guide for the utilities family (#1663) #1669.
• Reuses the shared welcome rules and generated footer, without changing the Issue Management skills' runtime behavior.
• Covers all eight Issue family skills and their respective configuration requirements.
• The new case-11-issue-first-run fixture uses the triage skill with surface_hash: sha256:fb90bdc45aec5f8a.
• Regression coverage explicitly distinguishes the Issue family magpie-issue-triage entry from the Security family issue-triage entry to prevent incorrect family resolution.
• Updates the setup evaluation case counts and regenerated general welcome report.

AI assistance disclosure: AI assistance was used for repository inspection, implementation drafting, and review. Changes were applied and validated locally by the contributor.

[KatalKavya96]

Hi @potiuk,

I've implemented the Issue Management family welcome guide for #1656, following the established approach from #1669.

It covers all eight skills, their configuration requirements, example workflows, and confirmation boundaries. I've also included the README integration, first-run evaluation fixture, and regression tests, including coverage for the triage skill naming collision between the Issue and Security families.

All repository-wide checks passed locally with prek run --all-files.

Thanks!

[potiuk]

Adds the issue-family first-run welcome guide covering all eight issue skills, with a careful test that magpie-issue-triage resolves to the issue family while bare issue-triage stays security; the fixture's triage surface hash is correct and each config file it names matches the skill's requires_config.

I pushed two commits rather than send this round again:

• 92f5bc7 — wording. Step 3 read "Reproduce a bug, then reassess its evidence", but reassess sweeps resolved or end-of-life issues against today's code, so it is now its own step ("re-assess old issues"). Two sentences that shared a line are split (semantic line breaks), and docs/issue-management/README.md now points at the guide with the same block the other family READMEs use, which also tells the reader how to bring it back.
• e37a9a8 — merge of main. The mentoring (#1708) and pairing (#1706) guides landed first and claimed the same slots, so this fixture moves to case-13-issue-first-run, the setup case counts go to 133, the test lists carry all three families, and the case-9 report is re-rendered.

The earlier red check was a cancelled CodeQL run, not a failure; the push re-runs it. Thanks for the guide!

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.