Write-up

Why

A commit preserves a diff and a one-line message. A pull request adds a title and whatever the author had the patience to type into the description box. Neither preserves the three approaches that were tried and abandoned, the constraint that made the obvious design impossible, or the one function that turned out to be the whole trick. That context lives in a chat transcript nobody will ever reopen.

The gap is worst exactly where it hurts most: six months later, when someone (often the original author) asks why a thing was built this way and the honest answer is that nobody remembers. The goal here was to capture that reasoning at the moment it is still cheap to capture, in a format someone would actually read.

What

• A Claude Code skill that writes <outputDir>/<branch>.html from what the model already holds in session context, in six fixed sections: Why, What, How, Decisions, Day by day, Highlights.
• Decisions is an Architecture Decision Record log, so the choices that shaped the work stay scannable without rereading the whole article.
• A generated front page with full-text search, status filter chips, and hover previews of every article.
• Automatic "Referenced by" backlinks derived from a manifest, so the wiki cross-links itself without hand maintenance.
• Glossary hovercards for non-obvious terms, from a curated dictionary rather than runtime guessing.
• A gated Stop hook that asks for the article exactly once, at genuine wrap-up, and a day-journal entry once per working day.
• A POSIX sh Stop hook with no dependencies at all, and an optional Python CLI (init, build, digest, suggest, shot, sweep, doctor) for the mechanical jobs. Python is never required.
• Installed as a plugin in two commands, which wires the hook without anyone editing settings.json.
• A home wiki at ~/.claude/write-ups/ for work that is not a branch and may not be code: research that reached an answer, a decision argued out over one session.

How

1. Started from the observation that the model already knows the story at the end of a session. No mining, no summarisation pass: chose "write from live context" over "reconstruct from the transcript" because reconstruction is expensive and produces a worse story than the one already in working memory.^[1]
2. Fixed the article structure instead of letting each one find its own shape. Six sections, always in the same order, so a reader who has seen one article can skim any other. Chose a rigid skeleton over freeform prose because consistency is what makes a wiki scannable.
3. Made the page a single self-contained HTML file: styles inline, no build step, no framework, no network. Chose static files over a documentation site generator because a wiki nobody has to install is a wiki that still opens in three years.
4. Wrote the Highlights section as verbatim code rather than prose descriptions of code. A snippet you can copy is worth a paragraph explaining it, and it cannot drift into being wrong the way a summary can.
5. Generated the index rather than hand-maintaining it. An early version had the model append an entry per article; entries went missing for days because a hand-maintained list is a hand-forgotten list. Chose "scan the folder and rebuild" over "append on write".^[2]
6. Gated the Stop hook hard. It fires only when the tree is clean, the branch is ahead of the default branch, and the work is pushed, and then only if the article is missing or older than the newest commit. Chose a narrow gate over a reminder-on-every-turn because a hook that cries wolf gets disabled within a day.^[3]
7. Extracted the forge-specific URLs into .write-up.json, detected from the git remote at init time. GitHub, GitLab, Bitbucket, and Azure DevOps each get their own link patterns; an unrecognised host resolves to no links at all rather than broken ones.

Decisions

Day by day

Highlights

def ensure_runtime(wdir):
    """Copy any missing runtime asset into the wiki folder. Returns what it wrote."""
    written = []
    if not os.path.isdir(wdir):
        os.makedirs(wdir)
    for dest, src in RUNTIME_ASSETS.items():
        dpath = os.path.join(wdir, dest)
        spath = os.path.join(ASSET_DIR, src)
        if os.path.exists(dpath) or not os.path.exists(spath):
            continue
        shutil.copyfile(spath, dpath)
        written.append(dest)
    return written

tpl_path = os.path.join(ASSET_DIR, "index-template.html")
if not os.path.exists(tpl_path):
    # Fail loudly and non-zero. A quiet aside here lets the front page rot
    # unnoticed while new articles pile up behind it.
    print("wrote manifest.js (%d articles)" % len(items))
    die("index-template.html missing at %s; index.html NOT regenerated "
        "and the front page is now stale" % tpl_path, 2)

if os.path.exists(article):
    # Fire once more only if the article went STALE: commits landed after it was
    # written. A refresh patches deltas, it never regenerates (see SKILL.md).
    last = git("log", "-1", "--format=%ct")
    if not last or not last.isdigit():
        return 0
    if int(last) <= int(os.path.getmtime(article)):
        return 0

kind = (
    "github" if "github" in host
    else "gitlab" if "gitlab" in host
    else "bitbucket" if "bitbucket" in host
    else None
)
if not kind:
    return forge
repo_url = "https://%s/%s" % (host, path)
t = FORGE_TEMPLATES[kind]
forge.update(
    type=kind,
    repoUrl=repo_url,
    branchUrl=t["branchUrl"].format(repo=repo_url, branch="{branch}"),
    fileUrl=t["fileUrl"].format(repo=repo_url, branch="{branch}", path="{path}"),
)

last_doc=$(git log -1 --format=%H -- "$article" 2>/dev/null)
if [ -n "$last_doc" ]; then
  since=$(git rev-list --count "$last_doc..HEAD" -- . ":(exclude)$article" 2>/dev/null)
  if [ "${since:-0}" -gt 0 ] 2>/dev/null; then
    block "$since commit(s) landed on $branch after $article was last updated. ..."
  fi
fi

Open

Window-targeted screenshots work on Windows only; every other platform gets full-screen capture, and web pages are better captured with the browser tools anyway. Closing an article out after its pull request merges is a separate opt-in command, writeup.py sweep, supporting GitHub through the gh CLI and Azure DevOps through a personal access token. It is the only part of the tool that makes a network call, it never runs on its own, and the Stop hook never touches the network. The macOS and Linux capture fallbacks are written against the standard tools but have not been exercised on those platforms. Two people adding articles to the same repo wiki on different branches still conflict in manifest.js, because both insert at the top; the entries are one per line now, so the conflict is readable and resolved by keeping both, but it is not gone. And the format has only been proven by articles this author wrote: whether a different model on a different codebase reaches for the right section is still untested.

References

1. plugin/scripts/writeup.py — the whole toolchain: init, build, digest, suggest, shot, sweep, doctor.
2. plugin/assets/index-template.html — the front page shell the build fills with entries.
3. plugin/SKILL.md — the authoring rules the model follows, including the refresh and final-sweep modes.
4. plugin/hooks/write-up-hook.sh — the Stop-hook gate, POSIX sh