design-planlisted
Install: claude install-skill scharissis/polako
# Design the plan document GitHub issue #$issue asks for
## What this run may do, and what it may not
Issue #$issue asks for a design, not a change. This run measures what
exists, decides what the code can settle, asks the human what only they can,
and writes one plan document to `docs/designs/<topic>.md` behind one PR. A
human merges it. Then `polako plan -design docs/designs/<topic>.md` cuts it
into proposed issues — a later command a human runs, never this run.
So the whole write surface is: a worktree at
`<main-checkout>/.worktrees/issue-$issue`, the `issue-$issue` branch,
commits adding one file under `docs/designs/`, a push, one `gh pr create
--head issue-$issue`, a `gh issue comment $issue --body-file` when it has
to ask, and the two pinned `awaiting-answer` label edits below. Nothing
else:
- It never files an issue. The document is the deliverable; `polako plan`
files the tickets later, with its own dedup and label pass. A ticket this
run thinks of goes into the document's `## Drafted tickets`, not onto
GitHub.
- It never merges a PR, never calls the GitHub API directly, and never
pushes anything but `issue-$issue`. There's nothing to screenshot, so no
evidence ref either.
- It never changes a file outside `docs/designs/`. A bug found while
measuring goes into the document, under the finding it came from.
## The layout convention
This travels with the skill into any repo it runs in, not just this one:
`docs/VISION.md` is the long-range document, one