Nextclaw Iteration Log Governance

NextClaw Iteration Log Governance

When To Use

Use this skill during the closing phase when a task may need docs/logs records.

Do not create an iteration directory at task start only for note-taking unless the user explicitly asks or the relevant iteration already exists.

Decision Rules

Create or update an iteration record when the work has independent delivery or traceability value:

• a commit or release batch is being closed,
• code/runtime changes span modules or a long-running delivery,
• an important root-cause fix or red-zone touch needs durable evidence,
• non-code content changed at large scale, such as governance/rule-system restructure,
• historical iteration records are being materially corrected or expanded,
• release or NPM package state must be recorded.

Do not automatically create an iteration record for:

• uncommitted local edits,
• a small isolated bugfix, test adjustment, style change or refactor with no red-zone/release significance,
• metadata, wording, index, thought, plan, design, PRD or discussion-doc updates,
• work that already belongs to an active related iteration and only needs a later batch-level update.

The user can explicitly request logging at any time. Otherwise, prefer one batch record over one record per task or correction.

Thought/design/plan/PRD documents normally belong under docs/thoughts, docs/plans, docs/designs, or docs/prd, not docs/logs.

Thought / Design / Plan Date Prefix

The iteration mechanism requires dated anchors and dotted role suffixes for thought, design, and plan deposits:

• files under docs/thoughts must use YYYY-MM-DD-<topic>.thought.md,
• files under docs/designs must use YYYY-MM-DD-<topic>.design.md,
• files under docs/plans must use YYYY-MM-DD-<topic>.plan.md,
• this rule applies even when the work does not need a docs/logs iteration record.

Same-Batch Rule

If the work is a micro-adjustment, verification fix, or follow-up in the same problem domain and same closing window as the most recent related iteration, update that iteration README.md.

Create a new iteration only when the goal has changed, impact expanded, a new independent batch started, a release/commit loop closed, or the user explicitly asked for separate traceability.

If a tiny new iteration was created by mistake, merge its useful content back into the related iteration and remove the mistaken directory.

Version Rule

Before creating a new directory:

find docs/logs -maxdepth 1 -type d -name 'v*' | sort

Only directories matching v<semver>-<slug> count. The new semver must be strictly greater than the maximum valid existing version.

Directory shape:

docs/logs/v<semver>-<slug>/README.md

README Required Sections

Every iteration README.md must contain:

1. ## 迭代完成说明
2. ## 测试/验证/验收方式
3. ## 发布/部署方式
4. ## 用户/产品视角的验收步骤
5. ## 可维护性总结汇总
6. ## NPM 包发布记录

If the task is a fix, incident, root-cause investigation, or abnormal-behavior cleanup, the completion section must record:

• root cause,
• how it was confirmed,
• why the fix targets the root cause rather than only the symptom.

If root cause is not fully known, explicitly write 根因未完全定位 with current gaps and next actions.

NPM Release Record

Always fill this section.

If no package release is involved, write 不涉及 NPM 包发布.

If release is involved, list:

• whether release is needed and why,
• exact package names,
• current published/unpublished state for each package,
• 待统一发布 status when a package must follow a later batch release,
• external blockers or trigger conditions.

Maintainability Summary

Always fill this section.

Cover:

• whether best effort was made to improve maintainability,
• whether deletion/simplification/code-less/clearer-boundary principles were followed,
• whether code/branch/function/file/directory sprawl decreased or at least did not worsen,
• whether abstractions and owner boundaries became clearer,
• whether directory/file organization satisfies current governance,
• whether the automatic guard found anything and whether its result triggered the subjective review reference,
• or 不适用 with reason when no code maintainability evaluation applies.

Work Notes

For complex, long-running, or cross-context tasks, create process notes only inside an existing or required iteration:

docs/logs/v<semver>-<slug>/work/working-notes.md

Reference work notes from the iteration README.md.

Red-Zone Touches

If source red-zone files are touched, add:

## 红区触达与减债记录

### <repo-path>

- 本次是否减债：
- 说明：
- 下一步拆分缝：

Use the maintainability guard output and scripts/governance/maintainability/maintainability-hotspots.mjs as the source of truth.

Closing Output

At final response time, state:

• whether an iteration record was required,
• the reason,
• the iteration path if created or updated,
• why no record was needed if skipped.