Add generic issue/PR/revision authoring skill

[devkade]

Summary

Add a bundled issue-pr-revision-authoring skill to Ilchul so Hermes can load one generic authoring contract for GitHub issue drafting, PR body drafting, and review revision explanations across repositories.

The desired style is execution-design authoring: an issue or PR should be detailed enough that an implementer/reviewer can proceed without a separate meeting. The reference shape is similar to:

• lablup/bssh issue 75 — implementation-ready issue with CLI contract, file list, example output, dependencies, security considerations, and testing plan.
• lablup/bssh issue 68 — current-state issue with status table, implemented surfaces, remaining work, and acceptance status.
• lablup/bssh issue 187 — measurement-driven performance issue with environment, measurements, hypotheses, investigation directions, and reproduction.
• lablup/bssh PR 201 — PR body with problem split into defects, changes by surface, tests, verification, behavior comparison, and acceptance criteria.
• lablup/bssh PR 190 — PR body with summary bullets, cleanup-path coverage table, explicit design decision, signal-handler observation, and test plan.

Context

Ilchul is the Hermes-connected development harness/repo. The harness should carry reusable authoring standards, but it should not encode repo-specific reviewer bots, branch policy, merge gates, or profile authority semantics.

The reusable PR body template name has been normalized from pr-83-level-body.md to pr-body.md in the current Hermes skill surface. This issue tracks bringing the same generalized authoring contract into Ilchul as a bundled skill, upgraded from a compact contract issue into an execution-design issue.

Problem

Current authoring guidance is scattered across workflow-specific surfaces and includes historical/product-specific vocabulary. That makes it easy to mix three layers that should stay separate:

• generic issue/PR/revision writing standards;
• repo-specific GitHub/reviewer/merge workflow policy;
• Hermes/Ragna supervision or authority semantics.

Ilchul should provide the first layer only, but it should do so with enough specificity that implementers can produce high-quality issues, PR bodies, and revision comments without re-learning the expected shape each time.

Proposed Skill Layout

Create a bundled skill such as:

skills/software-development/issue-pr-revision-authoring/
  SKILL.md
  templates/
    issue.md
    pr-body.md
    revision-comment.md

The skill should standardize:

1. issue authoring as an implementable work contract;
2. PR body authoring as an engineering report, not a changelog;
3. revision-comment authoring as a mapping from prior feedback to current-head changes and verification evidence.

Execution Design Principles

The bundled skill should teach three depths rather than one rigid template.

1. Issue as execution design

Use this when implementation should be possible directly from the issue.

The issue should include the relevant implementation contract:

• problem and motivation;
• proposed solution;
• concrete CLI/API/UX examples when applicable;
• files or surfaces likely to change;
• dependency/configuration changes;
• security/performance/compatibility considerations;
• testing and verification plan;
• acceptance criteria.

Reference pattern: lablup/bssh issue 75.

2. Issue as current-state tracker

Use this when a feature is partially implemented and the issue now tracks remaining work.

The issue should include:

• current implementation status summary table;
• feature/location table;
• completed goals vs remaining goals;
• current architecture or surface map;
• remaining work;
• acceptance criteria with status.

Reference pattern: lablup/bssh issue 68.

3. Issue as evidence-driven investigation

Use this when the issue is performance, correctness, or production-behavior driven and implementation should not start from guesses.

The issue should include:

• environment;
• measurements or reproduction evidence;
• observations separated from hypotheses;
• suggested investigations;
• reproduction commands;
• related issues/PRs.

Reference pattern: lablup/bssh issue 187.

Template: templates/issue.md

# Issue Authoring Template

Use the smallest section set that makes the work executable. Prefer execution-design detail over vague tickets.

## Summary

<One paragraph explaining what should change and where.>

## Problem

<What is wrong, missing, slow, ambiguous, or risky. Separate observed facts from guesses.>

## Context / Current state

<Why this matters now. Include relevant current implementation status, links, or code paths.>

Optional status table for partially implemented work:

| Feature / surface | Status | Location / evidence |
|---|---|---|
| <feature> | ✅ Complete / 🚧 Partial / ❌ Missing | `<path>` / <link> |

## Proposed solution

<The intended direction. Include enough detail that an implementer can start.>

## Contract / Examples

CLI/API/UX examples when applicable:

```bash
<command or usage example>
```

Expected output or behavior when useful:

```text
<output shape / behavior comparison>
```

## Implementation details

### Files / surfaces to modify

```text
<path>  # <expected change>
<path>  # <expected change>
```

### Dependencies / configuration

```toml
# if applicable
<dependency> = "<version>"
```

### Design decisions / options

1. **<Option A>** — <trade-off>
2. **<Option B>** — <trade-off>

Selected/default direction: <option or pending decision>.

## Security / Performance / Compatibility considerations

- <consideration>
- <consideration>

## Non-goals

- <what this issue should not do>

## Acceptance criteria

- [ ] <observable completion criterion>
- [ ] <test or behavior criterion>
- [ ] <boundary/non-goal criterion>

## Verification plan

- [ ] `<exact command or check>` — <expected result>
- [ ] <manual verification if needed>

## Related

- <issue/PR/doc link>

Template: templates/pr-body.md

# PR Body Template

A PR body is an engineering report, not a changelog. It should explain the problem, the selected design, what changed, how it was verified, and what remains risky.

```markdown
## Summary

- <1-3 bullets describing final behavior/result>
- <mention user-visible contract, compatibility, or regression coverage>

## Linked issue

Closes #<N>
<!-- Use Refs #<N> when the PR is partial and should not close the issue. -->

## Problem

<Explain what was wrong/missing, where it appeared, and why it mattered.>

If multiple defects surfaced under the same symptom, split them:

### Defect 1 — <name>

<fact-based explanation>

### Defect 2 — <name>

<fact-based explanation>

## Changes

### <Surface or file group> — `<path>`

- <specific behavior change>
- <specific guard/contract/test/doc update>

### <Surface or file group> — `<path>`

- <specific behavior change>

## Design decisions

<Explain selected option and why. Include explicit decisions such as centralizing cleanup, warning vs hard error, or preserving compatibility.>

Optional comparison table:

| Scenario / path | Before | After |
|---|---|---|
| <case> | <old behavior> | <new behavior> |

## Tests

- <new test file / test name> — <what it verifies>
- <existing test suite impact>

## Verification

- [x] `<exact command>` — pass, <count/detail if useful>
- [x] `<exact command>` — pass
- [ ] `<manual check>` — pending, reason: <why manual/maintainer-only>

If a check fails because of pre-existing unrelated failures, say so precisely and identify the affected files/checks.

## Acceptance criteria

- [x] <criterion from issue>
- [x] <criterion from issue>
- [ ] <remaining/manual criterion if any>

## Risks / Follow-up

- <remaining risk, limitation, or `None identified`.>
- <follow-up issue or `None`.>
```

Template: templates/revision-comment.md

Revision comments should be current-head, feedback-addressing notes. They should not merely say “fixed.” The best reference pattern from lablup/bssh PR 190 and #201 is a top-level finalization/review-response comment with: intent, findings addressed, tests, docs, lint/format, remaining items, and readiness.

# Revision Comment Template

Use after responding to review feedback or adding follow-up commits.

```markdown
## Revision explanation for current head `<HEAD_SHA>`

### Intent

<One sentence restating what this revision is closing.>

### Findings addressed

- [x] **<Finding title / severity if known>** — <what was changed and why it closes the feedback>
- [x] **<Finding title>** — <resolution>

### What changed

- `<path>` — <specific revision change>
- `<path>` — <specific revision change>

### Tests / verification

- [x] `<exact command>` — pass, <count/detail if useful>
- [x] `<exact command>` — pass
- [ ] `<manual check>` — pending/skipped, reason: <reason>

### Documentation / release notes

- `<path>` — <doc/changelog update>
- `n/a` — <reason if no docs needed>

### Remaining items

None.
<!-- Or list remaining non-blocking follow-up items explicitly. -->

### Ready for review

This revision is ready for review on current head `<HEAD_SHA>`.
```

If a repository requires a trigger phrase, mention it according to that repository's workflow. Do not bake a specific bot name or trigger phrase into this generic template.

Implementation Notes

• SKILL.md should explain when to choose execution-design issue vs current-state tracker vs evidence-driven investigation.
• The skill should explicitly say: choose the smallest useful structure, but do not omit concrete contracts when they prevent implementation ambiguity.
• Keep examples generic. Use placeholder commands and paths rather than bssh, kapi-agent, or repo-specific automation unless shown as external references.
• If referencing source examples, link them as examples only; do not turn their project-specific policies into generic Ilchul policy.

Scope

• Add the bundled issue-pr-revision-authoring skill.
• Add templates/issue.md with execution-design, current-state, and evidence-driven issue structures.
• Add templates/pr-body.md with engineering-report sections informed by lablup/bssh PR 201 and #190.
• Add templates/revision-comment.md with current-head revision/finalization structure informed by the PR comments in lablup/bssh PR 201 and #190.
• Keep wording generic enough to apply across repositories.
• Reference the new skill from any relevant Ilchul workflow docs if they need a shared authoring contract.

Non-goals

• Do not encode a specific reviewer bot name or trigger phrase in the generic bundled skill.
• Do not encode branch protection, ruleset, merge, deploy, or required-check policy.
• Do not encode GitHub App internals, webhook behavior, or CI rerun mechanics.
• Do not encode Hermes profile hierarchy, Ragna/일출 authority framing, or Discord lane policy.
• Do not use kapi or ilchul as reusable code identifiers for generic authoring primitives.

Acceptance criteria

• Ilchul contains a bundled issue-pr-revision-authoring skill with SKILL.md and the three templates above.
• The PR template is named pr-body.md, not pr-83-level-body.md.
• issue.md supports execution-design issues, current-state tracker issues, and evidence-driven investigation issues.
• pr-body.md includes problem/defect split, changes by surface, explicit design decisions, tests, verification, behavior comparison, acceptance criteria, and risks/follow-up.
• revision-comment.md includes current-head SHA, findings addressed, what changed, tests/verification, docs/release notes, remaining items, and ready-for-review statement.
• The skill describes authoring contracts only and keeps repo-specific review/merge policy out of scope.
• Revision guidance is generic: if a repo requires a trigger phrase, it says to follow that repo's workflow rather than naming a specific bot.
• Any references from existing workflow docs point to the new generic skill without moving repo-specific policy into it.

Verification

• Search the new bundled skill for repo-specific leakage: kapi-agent, branch protection, merge gates, Discord lane policy, and profile authority wording should not appear except as explicit non-goal examples if needed.
• Verify the skill and template paths exist.
• Verify template file names:
  • templates/issue.md
  • templates/pr-body.md
  • templates/revision-comment.md
• Run the repo's existing validation/test command if available.