kanban-archive

Close a PASS-reviewed feature or bug with kf archive. Features require a completion report and canonical docs; bugs update related docs only when needed. Use at review with current PASS reports or whe

SKILL.md

GitHub

Kanban Phase 6 — Artifact (Autonomous)

Argument: <feature_name>.

Close the work item with traceable results and the appropriate documentation.

Archive is the delivery gate, not just lifecycle bookkeeping. kf archive is the post-delivery step: it refuses while a recorded pr is not verifiably merged (exit 1, no side effects, no --force escape), and a review-PASS item legitimately waits in review until its change lands — visible as "awaiting merge" in kf status/kf doctor. With no pr recorded, running archive is the human's delivery confirmation. Only then does it move to dones, sync canonical docs, close the issue, move the board and stamp delivered — all idempotent, so a re-run reconciles.


1. Prepare closure artifacts

kf status --change {feature_name}
kf status --change {feature_name} --json

Require current PASS testing and review reports. Read kind before choosing closure work:

  • Feature: use kf instruct feature-report --change {feature_name} and write phase-6-feature-report.md in the review folder. Include actual changes, test/review evidence, documentation manifest, limitations and accepted follow-ups.
  • Bug: no feature report or feature planning artifacts are required. Read the bug report and review result; confirm the verified fix, regression evidence and docs impact.

If already in dones, complete only missing closure work and validate; never reimplement.

2. Sync docs

For a feature, let kf archive copy requirement, UC index/files/diagram and test plan/current result into canonical docs. The requirement mirror under docs/requirement/ was already written in Phase 1 — kf archive rewrites it from the Phase 1 artifact. Every canonical copy except the test result is stamped status: archived, and the UC index rows flip from planned to implemented. Do not manually copy the UC index/files, diagram or test plan before archive, and do not change approved source artifacts during closure.

2b. Reconcile superseded docs (feature, mandatory)

docs/ must describe the system as it is after this feature, not as each older feature left it. Before kf archive, read reconcile.md and follow it: find earlier canonical docs and docs/workflow/* that describe behavior this feature changes, mark contradicted snapshots with a Superseded by banner, bring workflow docs up to date, and record the result in the feature report's ## Docs Reconciled section (None — <reason> when nothing is affected). Never rewrite another feature's snapshot body.

For a bug, update existing related feature docs only when the fix changes documented behavior or reveals inaccurate documentation. Use the feature/context named in the bug report; do not overwrite feature docs with bug-report content. Record bug ID, fix summary and regression reference in the project's changelog or change-history section (e.g. CHANGELOG.md) when one exists. If behavior is already documented correctly, leave docs as-is and record “No documentation update required” with the reason in the review report. Bug archive does not automatically create canonical feature docs.

3. Archive and validate

kf archive {feature_name}
kf validate --change {feature_name}

kf archive requires current PASS reports, verifies a recorded PR is merged (or takes the human's run as confirmation), runs the dones hook — which closes the issue and moves the board to statusMap.dones — moves review → dones, syncs canonical docs for a feature and stamps delivered/deliveredAt last. Bugs skip canonical docs. kf stage ... dones uses the same archive path, so the merge gate applies there too. If it refuses on an unmerged PR, the item is not done — merge the PR first. Validate after archive and check reported canonical destinations for a feature. Do not report completion if validation fails.

When refreshing an item already in dones, canonical docs may include later bug fixes. If the CLI reports changed canonical docs, preserve them with --skip-specs; do not use --force to restore an older snapshot without explicit user direction — a forced overwrite is recorded as a bypass.

4. Git handoff

git status

Archive runs after the feature's change has merged, so its output is a docs-only change on top of the default branch. Commit when the user requested it or project instructions explicitly require it, on its own branch and PR:

  • Feature: docs({context}): sync canonical docs for {feature_name} — the canonical copies plus the docs reconciled in step 2b.
  • Bug: docs({context}): ... for related docs updated in step 2, when any.

Include only this work item's changes, respect ignored .works directories and preserve unrelated working-tree changes. Otherwise report that changes are uncommitted.


Done

Pipeline complete. Deliver the final report:

## Pipeline Complete: {context}/{feature_name}
1. ✓ Confirm — requirement or bug triage
2. ✓ Plan — approved feature contract or lightweight bug contract
3. ✓ Implement — {M}/{M} tasks
4. ✓ Test — {N}/{N} passed
5. ✓ Review — PASS
6. ✓ Archive — kf archive, docs sync/update status, docs reconciled: {list or None}

Artifacts: .works/dones/{feature_name}_{timestamp}/
Feature canonical docs:
- docs/requirement/{context}/{feature_name}.md
- docs/use-cases/{context}/{feature_name}/README.md
- docs/use-cases/{context}/{feature_name}/UC-###(-<slug>).md (one file per use case)
- docs/use-cases/{context}/{feature_name}/diagram.md
- docs/testplan/{context}/{feature_name}.md
- docs/testplan/{context}/{feature_name}-result.md

For bugs, list only related docs actually updated, or state why none were needed. Report the commit SHA only if a commit was made.