zf-backlog-batch-closeout

Files (1)

• SKILL.md

SKILL.md (first lines)

# ZaoFu Backlog Batch Closeout

## Objective

Turn an approved backlog batch into verified code, local commits, archived
`tasks/` records, and an auditable merge-ready worktree handoff without pushing
or sweeping unrelated work into history.

Default repository-facing output is Chinese unless the user asks otherwise.

## Preconditions

- Read `AGENTS.md` and follow ZaoFu backlog, task, commit, and verification
  rules before acting.
- Use this skill only after the user has approved implementation of specific
  backlog/task items or asks to close out a completed batch.
- Do not turn analysis-only discussion, vague ideas, or unapproved candidates
  into active tasks. Put those in `backlogs/` or `ideas/` only when requested.
- Never push. If the user asks to push, switch to the commit/push skill after
  this closeout is complete.
- Never stage unrelated dirty files. If the worktree contains unrelated
  changes, list them and leave them unstaged.

## Batch Model

Use this lifecycle:

```text
backlogs/<item>.md   --approval--> tasks/active/<item>.md
implementation       --verify-->   implementation commit
tasks/active/<item>.md --hash-->    tasks/done/<item>.md
archive metadata     --commit-->   archive commit
worktree             --audit-->    merge-ready handoff
```

Two commits are preferred because `done` task records require the short hash
and title of the implementation commit:

1. implementation commit: code/docs/tests for the approved work;
2. archive commit: task files updated to `> 状态: done` and moved to
   `tasks/done/`.

If the approved batch is docs/task-file-only and there is no implementation
diff, make one archive commit and clearly say why there is no implementation
commit.

## Workflow

1. Identify approved scope:
   - list exact backlog/task files and source design docs;
   - reject ambiguous "everything" if unrelated proposed items are present;
   - keep unapproved items in `backlogs/`.
2. Activate:
   - `backlogs/` is gitignored (`.gitignore:48`), so typical candidates are
     untracked — `git mv` fails there (`fatal: not under version control`).
     Move with `mv backlogs/<file>.md tasks/active/` then
     `git add tasks/active/<file>.md`;
   - only for the rare already-tracked file does `git mv backlogs/<file>.md
     tasks/active/` apply;
   - if a task is already in `tasks/active/`, keep its path;
   - preserve UTC filename and existing content.
3. Implement:
   - make the requested code/docs/test changes;
   - keep runtime state out of git;
   - update relevant design/impl/manual docs when behavior changes.
4. Verify:
   - run `python scripts/dev-verify.py plan --base dev` from the source
     worktree, inspect the changed-file/domain/reason output, then run the
     matching `python scripts/dev-verify.py run --base dev`;
   - if an approved source change is intentionally outside the known map,
     pass exact `--tests <path>` values and record why they close the impact;
     never weaken the selector or treat an unknown source path as no-test;
   - for skill-only changes, validate changed skills when a validator exists;
   - record exact commands and results for task archival.
5. Implementation commit:
   - inspect `git status --short --branch`, `git diff --stat`, and relevant
     diffs;
   - stage only implementation files and active task files if activation must
     be recorded with the implementation;
   - commit with a conventional prefix;
   - do not push.
6. Implementation completeness audit:
   - run `git status --short --untracked-files=all` after the implementation
     commit;
   - classify every residual path as approved-task work, unrelated pre-existing
     work, generated/runtime output, or a follow-up task;
   - if approved-task work remains, do not archive the task as done: finish and
     verify it, or report the exact blocker;
   - never make a dirty worktree appear clean with broad staging, destructive
     reset, or deletion.
7. Archive:
   - get `git log -1 --oneline`;
   - update each completed task's first paragraph to `> 状态: done`;
   - include the short hash + commit title and a concise verification summary;
   - move completed files to `tasks/done/` with `git mv`.
8. Archive commit:
   - stage only task archive files;
   - commit with `docs:` or `chore:` as appropriate;
   - do not push.
9. Prepare the merge handoff:
   - capture `worktree` with `git rev-parse --show-toplevel`, `branch` with
     `git branch --show-current`, and `source_head` with `git rev-parse HEAD`;
   - run `git status --short --untracked-files=all` again after the archive
     commit;
   - for a `wip/*` branch, set `merge_ready=true` only when the worktree is
     clean; otherwise set `merge_ready=false`, list every residual path, and
     leave the worktree and branch intact;
   - for a direct commit on `dev`, report `merge_ready=not_applicable`;
   - once a worktree is declared merge-ready, freeze it. Any later write
     invalidates the handoff and requires this audit again;
   - do not remove the worktree here. Final merge and cleanup belong to
     `zf-harness-commit-push` running from the designated `dev` merge-owner
     checkout.
10. Report:
   - implementation commit, archive commit, and branch;
   - task files moved to `tasks/done/`;
   - verification commands and outcomes;
   - worktree, source HEAD, merge-ready status, and every residual path;
   - any items intentionally deferred.

From uisee-ai/zaofu, Apache-2.0.

More from uisee-ai/zaofu