/hermit-scribe

name: hermit-scribe
description: File a GitHub issue or post a comment on an existing issue via a GitHub App bot identity. Use when the operator says "file as a GH issue", "open an issue for T-YYYYMMDD-HHMMSS, a task handle or PROP-NNN", "report this to the tracker", "add a comment to issue #NNN", "comment on #NNN", "reply to issue #NNN", or similar. Requires HERMIT_GH_APP_ID, HERMIT_GH_APP_INSTALL_ID, HERMIT_GH_APP_KEY_FILE in env.

hermit-scribe

Files a GitHub issue or posts a comment on an existing issue via a configured GitHub App bot identity.

When to activate (filing)

Activate when the operator says:

• "file T-YYYYMMDD-HHMMSS as a GH issue"
• "file <task handle> as a GH issue"
• "file PROP-NNN as a GH issue"
• "open an issue for this"
• "report this to the tracker"
• "file a GH issue for [description]"

When to activate (commenting)

Activate when the operator says:

• "add a comment to issue #NNN"
• "comment on #NNN: [text]"
• "reply to issue #NNN"

How to file

**Step 1: resolve content.**

If the operator named a T-id, a task handle or an older `PROP-NNN` id: 1. Run `.hermit/bin/hermitd-run task list .hermit --all --json`, appending `--id <T-id>`, `--handle <handle>` or `--dedupe-key proposal:PROP-NNN` as appropriate. For an older proposal id, retry it zero-padded to three digits. No row: stop. Several rows: list them and ask which one. 2. Read `.hermit/tasks/<id>.md` for `id`, `title`, `category` and `dedupe_key`. 3. Read the `## Proposal` section through the end of the file or a trailing `## Lessons` heading. For migrated records, exclude the leading `---` frontmatter block inside that section from the draft, retaining its metadata for dedup below. Include Context, Problem, Proposed Solution and Impact when present. 4. Derive the Conventional-Commits type, scope, and labels. Write the **raw** (pre-translation) frontmatter `title` and proposal body to temp files, then run:

   bun "${CLAUDE_SKILL_DIR}/file-issue.ts" classify {category} {title-file} {body-file}

It emits JSON `{type, scope, labels, title_line}` — `title_line` is `<type>(<scope>): <title>` (scope omitted when unresolved). Review it, then use `title_line` as the draft title and hold `labels` for Step 6. (Scope resolution reads `_hermit_versions` from `.hermit/config.json`; `hermit-filed` is added by the script — it is not in `labels`.)

5. Construct the draft body from the Proposal section. The provenance footer (see Step 3) is NOT part of the draft — appending it here would expose `proposal={id}` to the sanitizer, which would redact it as operator-project detail and break dedup.

For ad-hoc issues (no proposal): use the title and body the operator provides verbatim — no CC type/scope construction.

Then, for both proposal-backed and ad-hoc issues:

**Step 1b: language normalization.**

If the title or body is not already in English, translate to English. Preserve verbatim:

• Technical identifiers (entity IDs, API names, file paths, function names, package names, plugin slugs, repo names)
• Code blocks and command lines
• Frontmatter field names and values
• Proper nouns

Translate prose, headings, and bullet text. Keep the structure (Context / Problem / Proposed Solution / Impact) and section ordering identical to the source.

The source task record is NOT modified — translation applies only to what is sent to GitHub.

**Step 1c: issue-template detection.** (both proposal-backed and ad-hoc issues)

Run:

bun "${CLAUDE_SKILL_DIR}/file-issue.ts" --templates

• Non-empty `templates` → hold the filenames for Step 4's preview. This checks the target repo (`HERMIT_GH_REPO`) directly via the GitHub API, not the local checkout, and only the modern `.github/ISSUE_TEMPLATE/` directory form; the legacy single-file `.github/ISSUE_TEMPLATE.md` is intentionally out of scope.
• Empty `templates` → hold nothing; Step 4's preview gets no template note.

These filenames are never passed to the Step 3 sanitizer and are never part of the draft or cleaned body — they reach the operator only through Step 4's preview.

**Step 2: dedup check.** (proposal-backed only — skip for ad-hoc issues)

Run:

bun "${CLAUDE_SKILL_DIR}/file-issue.ts" --check {id}

For migrated records whose `dedupe_key` is `proposal:PROP-NNN`, also run:

bun "${CLAUDE_SKILL_DIR}/file-issue.ts" --check PROP-NNN

Treat the proposal as filed if either check returns `exists`, the migrated frontmatter has a `gh_issue:` URL, or `## Decisions` holds a `GitHub issue:` note. Show all known issue URLs and ask whether to skip filing or proceed anyway. Only continue without asking when none of these signals exists.

**Step 3: sanitize.**

Pass the draft title and body to the `hermitd-scribe:issue-sanitizer` subagent:

DRAFT_TITLE: {draft title}
DRAFT_BODY:
{draft body}

Parse the response: split on the `<<<HERMIT_SCRIBE_BODY>>>` line. Everything before it (after stripping `TITLE: `) is the cleaned title; everything after is the cleaned body.

For proposal-backed issues, append the footer to the cleaned body now — after sanitization, never before it, since the footer is skill-generated protocol that `--check` matches on, not operator content:

---
*Filed via hermit-scribe · proposal={id}*

**Step 4: operator preview.**

Present the post-translation, post-sanitization content to the operator as a **single message** containing, in order: 1. Proposed title 2. Complete issue body — everything that will be written to the issue, including the `---\n*Filed via hermit-scribe...*` footer 3. Labels that will be applied (informational — no operator editing): `Labels: hermit-filed (always); plus bug/enhancement/chore and optional homeassistant-hermit/hermit-scribe for proposal-backed issues` 4. If Step 1c found templates (informational — no operator editing): `Note: this repo defines issue templates under .github/ISSUE_TEMPLATE/ ({filenames}); this body does not follow them.` Omit this item entirely wh