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