closing-issues

Closing Issues

A flowing graph that turns "close GitHub issue + capture what I learned" into a structural DAG. The synthesis text is validated upfront, the close happens against the GitHub API, and an optional post-close callback runs detached so the close ack is unblocked.

from closing_issues import close_issue

result = close_issue(
    repo="owner/repo",
    number=42,
    synthesis=(
        "Pattern X works because of Y. Constraint: don't apply to Z. "
        "Future note: revisit when feature Q lands."
    ),
)

print(result["issue_url"]) # https://github.com/.../issues/42 print(result["comment_url"]) # ...#issuecomment-...


## Why a synthesis, not a "done" comment

Closing an issue produces two artifacts:

- **The Issue itself** — implementation log. The diff and commit history
  already show *what* was done.
- **The closing comment / synthesis** — what was *learned*. Lasts longer
  than the diff in mental cache.

Good closing comments lead with *why*, not *what*. Failure modes,
constraints discovered, alternatives rejected. The synthesis is the
seed of an institutional memory.

## Internal shape

prepare_synthesis ──▶ close_github_issue [terminal] │ └──▶ post_close_callback [detached, when=callback]


- **`validate=must_have_synthesis_text`** runs against the raw input
  string. Empty or whitespace-only → FAILED with no GitHub API call.
  This is structural: callers can't accidentally close-with-no-text.

- **`close_github_issue`** posts the synthesis as a comment, then
  PATCHes the issue to `state=closed, state_reason=completed`. Returns
  the issue URL and comment URL.

- **`post_close_callback`** (optional) runs detached. Caller plugs in
  any extra work — store synthesis in a memory system, ping a tracker,
  emit a webhook. Failure here lands in `result["detached_failures"]`
  and does NOT bubble up as a close failure. Skipped via `when=` if
  the callback isn't provided.

## Pluggable post-close callback

```python
def store_in_my_memory(synthesis: str, issue_url: str, repo: str, number: int):
    # Whatever your memory layer is — Turso, sqlite, a JSON file, etc.
    db.execute("INSERT INTO learnings (issue, synthesis) VALUES (?, ?)",
               (issue_url, synthesis))
    return {"stored": True}

result = close_issue(
    repo="owner/repo",
    number=42,
    synthesis="...",
    post_close_callback=store_in_my_memory,
)

if result["callback_result"] is None and result["detached_failures"]:
    # The callback failed but the issue is still closed.
    print("Memory store failed:", result["detached_failures"])

The callback receives keyword arguments: synthesis, issue_url, repo, number. Anything it returns goes into result["callback_result"].

Result shape

{
    "issue_url":        "https://github.com/owner/repo/issues/N",
    "comment_url":      "https://github.com/.../issues/N#issuecomment-...",
    "comment_id":       12345,
    "callback_result":  <whatever the callback returned, or None>,
    "detached_failures": [],   # populated if callback raised
}

Raises RuntimeError only if the GitHub close itself fails. Callback failures are detached.

Auth

Requires GH_TOKEN (or GITHUB_TOKEN) in the environment. Classic PAT or fine-grained PAT with repo scope (specifically issues:write).

When NOT to use

Closing an issue without a synthesis. If you genuinely have nothing to say beyond "done," just gh issue close N directly. This skill is for the synthesis use case.
Closing many issues at once (use a script that calls this in a loop — fine, but the flow setup cost per call is small but not zero).

About this skill

Result shape

Auth

When NOT to use

See also