harness-issue

Files (3)

• SKILL.md
• prepare-pr-workspace.sh
• resolve-upstream.sh

SKILL.md (first lines)

# Harness Issue

Turn a lesson from a downstream project into an upstream Issue (a bug, gap,
or idea) or a Pull Request (a concrete fix) on the harness repository, without
leaving the project. It closes the loop between the projects that consume
harness-kit and the harness itself.

It needs `gh`, authenticated with access to the upstream repo, and a user
present to confirm the preview. PR mode also needs push access to the
upstream or to a fork of it.

Two rules hold in every mode. Show the full title and body and get the user's
confirmation before any `gh issue create` or `gh pr create`, so nothing is
filed silently. Write only facts you have: when the harness-kit version,
skill, or commit behind the finding is unknown, ask or write `(unknown)`
rather than inventing context to look thorough.

## 1. Resolve the upstream

```bash
upstream=$(${CLAUDE_SKILL_DIR}/resolve-upstream.sh)
```

The script is the lookup the update workflow uses too: `$HARNESS_UPSTREAM`,
then `.claude/harness-upstream` (one line, `owner/repo`), then, in a project
not yet migrated to a vendored snapshot, the first source `repo` in
`.harness-lock.json`, then its built-in default. Refer to the repo by the
resolved name in every message to the user rather than a hardcoded
`dougborg/harness-kit`. Done when `$upstream` holds an `owner/repo` and you
have told the user which repo you are filing against.

## 2. Choose the mode

Use `$ARGUMENTS` when it is `issue` or `pr`. Otherwise ask: "Issue (describe a
bug, gap, or idea) or PR (propose a concrete change)?" Done when the mode is
set.

## 3. Gather the context

From the conversation, pin down:

- **What**: the finding in one sentence.
- **Where**: the affected skill, agent, hook, script, or doc, with file path
  and line when known.
- **Why it matters**: the concrete impact (broke a workflow, surprised a user,
  blocked a feature).
- **Repro or suggested fix**: a minimal repro for a bug, a sketch of the fix
  for an idea.

Sanitize internal paths, customer names, and secrets before they reach the
draft, and ask the user when you're unsure whether something is sensitive.
Done when each of the four is filled in, asked about, or marked `(unknown)`.

## 4. Search for duplicates

```bash
gh issue list -R "$upstream" --state all --limit 20 --search "<keywords>"
gh pr list    -R "$upstream" --state all --limit 20 --search "<keywords>"
```

Search by topic, not by the title you were about to write: the same work is
often filed under a different framing (an issue saying "the standard is
documented but unenforced" can duplicate one saying "set up the testing
stack"). Try two or three phrasings of the underlying need.

Show the user any related matches and ask: file new, comment on the existing
thread, or abort. Commenting on an existing thread keeps the discussion in one
place: post with `gh issue comment` or `gh pr comment`, then skip to step 6.
Done when the user has chosen, or no open or recently closed item matches.

## 5a. Issue mode

First check the finding isn't already fixed on the default branch, merged but
not yet released: look at the merged PRs from step 4, and search commits
pushed directly:

```bash
gh api -X GET search/commits -f q="repo:$upstream <keywords>" --jq '.items[] | "\(.sha[0:7]) \(.commit.message | split("\n")[0])"'
```

When it is already fixed, tell the user and stop instead of filing.

Compose a title of 70 characters or fewer and this body:

```markdown
## What

<one-paragraph summary>

## Where

- File: `path/to/affected.md`
- Skill / agent: `<name>` (if applicable)
- harness-kit version: `<version from .harness/lock.json>` (or `unknown`)

## Why it matters

<impact>

## Repro / suggested fix

<minimal repro or sketch>

## Source context

Surfaced from project `<downstream-repo-name>` (or `unknown`) on `<date>`.
```

Show the user the full title and body, and after they confirm:

```bash
gh issue create -R "$upstream" --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)"
```

Done when the issue exists and you have its URL.

From dougborg/harness-kit, Apache-2.0.

More from dougborg/harness-kit