oaustegard/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

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).

See also

• flowing — the DAG runner this skill is built on
• opening-prs — the symmetric "open and merge" flow