Back to Details

pbs-phase-closure

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Phase Closure

阶段收尾

Overview

概述

Sync phase knowledge to global documents and prepare the next phase. This is the "CONSOLIDAR" step — it does NOT validate code quality (that's done by pbs-pr-hardening).
Core principle: The closure report is the bridge between phases. It reflects REALITY — what was actually built — and updates the project's shared knowledge base.
Announce at start: "I'm using the pbs-phase-closure skill to close phase [N] and prepare the handoff."
将阶段知识同步到全局文档，为下一阶段做准备。这是“整合”步骤——它不会验证代码质量（代码质量验证由pbs-pr-hardening完成）。
核心原则： 收尾报告是各阶段之间的桥梁。它反映的是实际情况——实际构建的内容——并更新项目的共享知识库。
启动时声明： “我正在使用pbs-phase-closure技能来收尾第[N]阶段，并准备交接工作。”

When to Use

使用时机

  • PR hardening is complete (review report resolved or clean)
  • Human approved the review results
  • Ready to formalize what happened and move forward
  • PR加固已完成（审查报告已解决或无问题）
  • 人员已批准审查结果
  • 已准备好正式记录阶段成果并推进后续工作

Input

输入

Phase artifacts (required):
  • .pbs-framework/phases/phase-XX/spec.md
    — what was planned
  • .pbs-framework/phases/phase-XX/tasks.md
    — how it was broken down
  • .pbs-framework/phases/phase-XX/review-report.md
    — review findings and resolutions
  • .pbs-framework/phases/phase-XX/pr-description.md
    — PR description (already generated by hardening)
  • Git log for the phase's commits — what actually changed
Global documents (for updating):
  • .pbs-framework/03-decision-log.md
  • .pbs-framework/04-roadmap.md
  • .pbs-framework/05-tech-debt-register.md
    (if exists)
  • .pbs-framework/06-architecture-snapshot.md
    (if exists)
阶段产物（必填）：
  • .pbs-framework/phases/phase-XX/spec.md
    — 计划内容
  • .pbs-framework/phases/phase-XX/tasks.md
    — 任务拆分方案
  • .pbs-framework/phases/phase-XX/review-report.md
    — 审查结果与解决方案
  • .pbs-framework/phases/phase-XX/pr-description.md
    — PR描述（已由加固步骤生成）
  • 对应阶段提交的Git日志 — 实际变更内容
待更新的全局文档：
  • .pbs-framework/03-decision-log.md
  • .pbs-framework/04-roadmap.md
  • .pbs-framework/05-tech-debt-register.md
    （如存在）
  • .pbs-framework/06-architecture-snapshot.md
    （如存在）

The Process

流程

Step 1: Load Phase Artifacts

步骤1：加载阶段产物

Read all artifacts from the completed phase:
  1. .pbs-framework/phases/phase-XX/spec.md
    — what was planned
  2. .pbs-framework/phases/phase-XX/tasks.md
    — how it was broken down
  3. .pbs-framework/phases/phase-XX/review-report.md
    — review findings and resolutions
  4. .pbs-framework/phases/phase-XX/pr-description.md
    — PR description
  5. Run 
    git log
    for the phase's commits — what actually changed
读取已完成阶段的所有产物：
  1. .pbs-framework/phases/phase-XX/spec.md
    — 计划内容
  2. .pbs-framework/phases/phase-XX/tasks.md
    — 任务拆分方案
  3. .pbs-framework/phases/phase-XX/review-report.md
    — 审查结果与解决方案
  4. .pbs-framework/phases/phase-XX/pr-description.md
    — PR描述
  5. 运行
    git log
    获取对应阶段的提交记录 — 实际变更内容

Step 2: Load Global Documents

步骤2：加载全局文档

Read these for updating:
  1. .pbs-framework/03-decision-log.md
  2. .pbs-framework/04-roadmap.md
  3. .pbs-framework/05-tech-debt-register.md
    (if exists)
  4. .pbs-framework/06-architecture-snapshot.md
    (if exists)
读取以下文档用于后续更新：
  1. .pbs-framework/03-decision-log.md
  2. .pbs-framework/04-roadmap.md
  3. .pbs-framework/05-tech-debt-register.md
    （如存在）
  4. .pbs-framework/06-architecture-snapshot.md
    （如存在）

Step 3: Generate Closure Report

步骤3：生成收尾报告

Generate 
.pbs-framework/phases/phase-XX/closure-report.md
using this template:
markdown
undefined
使用以下模板生成
.pbs-framework/phases/phase-XX/closure-report.md
：
markdown
undefined

Closure Report — Fase [N]: [Name]

Closure Report — Fase [N]: [Name]

Fecha de cierre

Fecha de cierre

[date]
[date]

Resumen

Resumen

[What was ACTUALLY built — 2-3 sentences. Not what was planned, what was delivered.]
[What was ACTUALLY built — 2-3 sentences. Not what was planned, what was delivered.]

Artefactos de la Fase

Artefactos de la Fase

  • Review Report: 
    .pbs-framework/phases/phase-XX/review-report.md
    — [status: resolved/clean]
  • PR Description: 
    .pbs-framework/phases/phase-XX/pr-description.md
  • Review Report: 
    .pbs-framework/phases/phase-XX/review-report.md
    — [status: resolved/clean]
  • PR Description: 
    .pbs-framework/phases/phase-XX/pr-description.md

Decisiones Nuevas

Decisiones Nuevas

(These MUST be copied to the Decision Log)
DecisionRazonFase
[what was decided][why][N]
If none: "No new decisions were made during this phase."
(These MUST be copied to the Decision Log)
DecisionRazonFase
[what was decided][why][N]
If none: "No new decisions were made during this phase."

Cambios respecto al diseno original

Cambios respecto al diseno original

  • [What changed vs the spec and why]
  • [Any contracts that were modified during implementation]
If none: "Implementation matched the original spec without deviations."
  • [What changed vs the spec and why]
  • [Any contracts that were modified during implementation]
If none: "Implementation matched the original spec without deviations."

Deuda Tecnica Generada

Deuda Tecnica Generada

(These MUST be copied to the Tech Debt Register)
QuePor que se dejoPrioridad
[what][why it was deferred]alta/media/baja
If none: "No new tech debt was generated."
(These MUST be copied to the Tech Debt Register)
QuePor que se dejoPrioridad
[what][why it was deferred]alta/media/baja
If none: "No new tech debt was generated."

Tests Creados

Tests Creados

TestTipoQue validaPasa
[test name/path]unit/integration/contract[what it validates]Si/No
TestTipoQue validaPasa
[test name/path]unit/integration/contract[what it validates]Si/No

Relevant Assets for Next Phase

Relevant Assets for Next Phase

(Files the next phase will likely need as context)
  • [file path] — [why it's relevant for what comes next]
  • [file path] — [why it's relevant]
(Files the next phase will likely need as context)
  • [file path] — [why it's relevant for what comes next]
  • [file path] — [why it's relevant]

Observaciones para la Siguiente Fase

Observaciones para la Siguiente Fase

  • [observation 1: something the next phase should consider]
  • [observation 2: a pattern discovered, a constraint found]
  • Pregunta quirurgica sugerida para el re-analisis:
    "[concrete question anchored to the next phase's objective]"
  • [observation 1: something the next phase should consider]
  • [observation 2: a pattern discovered, a constraint found]
  • Pregunta quirurgica sugerida para el re-analisis:
    "[concrete question anchored to the next phase's objective]"

Actualizacion de Documentos (checklist)

Actualizacion de Documentos (checklist)

  • Decision Log actualizado
  • Roadmap actualizado (estado + ajustes)
  • Tech Debt Register actualizado
  • Architecture Snapshot actualizado (si cambio la estructura)
  • Siguiente fase detallada en el roadmap

**Rules for closure report generation:**
- The "Resumen" MUST describe what was actually built, not what was planned. Compare git log with the spec.
- Every new decision MUST appear in "Decisiones Nuevas" — even small ones.
- "Relevant Assets" MUST NOT be empty. Every phase produces files the next phase needs.
- "Observaciones" MUST include a surgical question for re-analysis — this guides the next phase's planning.
- If changes were made vs the original spec, document WHY, not just WHAT.
- Spec compliance and code quality are NOT validated here — that was done by pbs-pr-hardening. Closure focuses on knowledge sync.
  • Decision Log actualizado
  • Roadmap actualizado (estado + ajustes)
  • Tech Debt Register actualizado
  • Architecture Snapshot actualizado (si cambio la estructura)
  • Siguiente fase detallada en el roadmap

**收尾报告生成规则：**
- “Resumen”部分必须描述实际构建的内容，而非计划内容，需对比Git日志和需求规范
- 所有新决策都必须写入“Decisiones Nuevas”，哪怕是很小的决策
- “Relevant Assets”部分不能为空，每个阶段都会产生下一阶段需要用到的文件
- “Observaciones”部分必须包含一个用于重新分析的精准问题，用于指导下一阶段的规划
- 如果实际实现和原需求规范有差异，要记录原因，而不仅仅是记录变更内容
- 此处不验证需求符合度和代码质量，该工作已由pbs-pr-hardening完成，收尾的核心是知识同步

Step 4: Update Global Documents

步骤4：更新全局文档

Decision Log (
.pbs-framework/03-decision-log.md
)

决策日志（
.pbs-framework/03-decision-log.md
）

  • Add every entry from "Decisiones Nuevas"
  • Use the existing format in the file
  • Include the phase number as origin
  • 添加“Decisiones Nuevas”中的所有条目
  • 使用文件中已有的格式
  • 注明决策来源的阶段编号

Roadmap (
.pbs-framework/04-roadmap.md
)

路线图（
.pbs-framework/04-roadmap.md
）

  • Mark this phase as completed
  • Update status indicators
  • Detail the NEXT phase: promote from "esbozada" to "definida"
    • Add concrete objective (informed by observations from this closure)
    • Add expected deliverable
    • Add known dependencies from this phase's output
  • Adjust remaining future phases if this phase changed assumptions
  • 将当前阶段标记为已完成
  • 更新状态标识
  • 细化下一阶段：将状态从“草稿”升级为“已定义”
    • 添加具体目标（结合本次收尾的观察结果）
    • 添加预期交付物
    • 添加当前阶段输出中已知的依赖项
  • 如果本次阶段改变了原有假设，调整剩余未来阶段的规划

Architecture Snapshot (
.pbs-framework/06-architecture-snapshot.md
)

架构快照（
.pbs-framework/06-architecture-snapshot.md
）

  • Update ONLY if the architecture actually changed during this phase
  • If this is Phase 1 and no snapshot exists, CREATE it
  • If no structural changes, do NOT touch this file
  • 仅当本阶段架构发生实际变更时才更新
  • 如果是第1阶段且不存在快照，则创建该文件
  • 如果没有结构变更，不要修改该文件

Tech Debt Register (
.pbs-framework/05-tech-debt-register.md
)

技术债务登记册（
.pbs-framework/05-tech-debt-register.md
）

  • Add every entry from "Deuda Tecnica Generada"
  • If the file doesn't exist and there is debt to register, create it
  • If no new debt, do NOT touch this file
  • 添加“Deuda Tecnica Generada”中的所有条目
  • 如果文件不存在且有债务需要登记，则创建该文件
  • 如果没有新增债务，不要修改该文件

Step 5: Verify Updates

步骤5：验证更新

REQUIRED: Use superpowers:verification-before-completion
Check that all documents were updated correctly:
  • Closure report exists and has all sections filled
  • Decision Log has the new entries (if any)
  • Roadmap shows phase as complete and next phase is detailed
  • Architecture Snapshot is current (updated or confirmed unchanged)
  • Tech Debt Register has new entries (if any)
  • The "Actualizacion de Documentos" checklist in the closure report is marked complete
必填： 使用superpowers:verification-before-completion技能
检查所有文档是否已正确更新：
  • 收尾报告已存在且所有章节都已填写
  • 决策日志已添加新条目（如有）
  • 路线图已标记当前阶段完成，且下一阶段已细化
  • 架构快照是最新的（已更新或确认无变更）
  • 技术债务登记册已添加新条目（如有）
  • 收尾报告中的“Actualizacion de Documentos”检查清单已标记为完成

Step 6: Present to Human

步骤6：向人员汇报

Summarize:
  • What was generated (closure report)
  • What was updated (list which global docs changed and what changed in each)
  • What the next phase looks like (objective, estimated scope)
  • Any open questions for the human before moving on
<HARD-GATE> The human MUST validate that: 1. The closure report reflects what actually happened (not what was planned) 2. Global documents are updated correctly 3. The next phase is properly detailed in the roadmap 4. Observations and surgical question make sense for the next phase
Do NOT proceed to the next phase's planning until the human approves. </HARD-GATE>
总结以下内容：
  • 生成了什么内容（收尾报告）
  • 更新了什么内容（列出变更的全局文档以及每个文档的变更点）
  • 下一阶段的概况（目标、预估范围）
  • 推进前需要向人员确认的未解决问题
<HARD-GATE> 人员必须确认以下内容： 1. 收尾报告反映了实际发生的情况（而非计划内容） 2. 全局文档已正确更新 3. 路线图中已详细说明下一阶段 4. 观察结果和精准问题对下一阶段具有合理性
在获得人员批准前，不得进入下一阶段的规划。 </HARD-GATE>

Common Mistakes

常见错误

  • Copying the plan as the closure — the closure reflects REALITY (git log), not aspirations (spec). Compare them.
  • Empty "Relevant Assets" section — every phase produces files the next phase needs. If you listed none, you missed something.
  • Forgetting the surgical question — the next phase's planning starts from this question. Without it, context is lost.
  • Not updating the Roadmap — the roadmap is a living document. Mark the phase complete and detail the next one.
  • 把计划内容直接复制到收尾报告中 —— 收尾反映的是实际情况（Git日志），而非预期（需求规范），需对二者进行对比
  • “Relevant Assets”章节为空 —— 每个阶段都会产生下一阶段需要的文件，如果没有列出说明有遗漏
  • 遗漏精准问题 —— 下一阶段的规划从这个问题开始，没有它就会丢失上下文
  • 不更新路线图 —— 路线图是活文档，要标记当前阶段完成并细化下一阶段

Red Flags

红色预警

Signs the agent is about to violate the process — STOP:
  • Copying the plan as the closure report → The closure reflects REALITY. Compare with git log.
  • Skipping "Observaciones para la Siguiente Fase" → This section IS the context handoff. Never skip it.
  • Not updating the Roadmap → The roadmap MUST be updated at every closure.
  • Empty "Relevant Assets" section → Every phase produces files the next phase needs. List them.
  • Forgetting to detail the next phase → Promoting the next phase from "esbozada" to "definida" is mandatory.
  • Not including the surgical question → The next phase's planning depends on this question.
  • Updating Architecture Snapshot when nothing structural changed → Only update if the architecture actually changed.
出现以下迹象说明Agent即将违反流程，立即停止：
  • 把计划内容复制到收尾报告 → 收尾反映的是实际情况，需和Git日志对比
  • 跳过“Observaciones para la Siguiente Fase”章节 → 这部分是上下文交接的核心，绝对不能跳过
  • 不更新路线图 → 每次收尾都必须更新路线图
  • “Relevant Assets”章节为空 → 每个阶段都会产生下一阶段需要的文件，请列出
  • 遗漏下一阶段的细化工作 → 必须将下一阶段从“草稿”升级为“已定义”
  • 未包含精准问题 → 下一阶段的规划依赖这个问题
  • 架构没有发生结构变更却更新架构快照 → 仅当架构实际变更时才更新

Common Rationalizations

常见借口

ExcuseReality
"The plan didn't change, so I'll just copy it"Git log tells the truth. The plan is aspirational; the closure is factual.
"Observations are optional for simple phases"Simple phases still produce context for the next phase. Write observations.
"The next phase is already clear in the roadmap"Detail it with what you now know from this phase's closure. Context changes plans.
"No new decisions were made"Did the agent or human make ANY choice not in the Decision Log? Even small ones count.
"The architecture didn't change so I'll skip the snapshot"Correct — if it didn't change, don't update it. But verify, don't assume.
"Tech debt is too minor to register"If it was noted during validation, register it. Future-you will thank you.
"I'll update the docs later"The docs are part of the closure. They get updated now or they never get updated.
借口实际情况
“计划没有变化，所以我直接复制就好了”Git日志记录了真实情况，计划是预期，收尾是事实
“简单阶段不需要写观察结果”即使是简单阶段也会为下一阶段产生上下文，必须编写观察结果
“路线图里已经明确了下一阶段”要结合本次收尾获得的信息细化下一阶段，上下文会改变规划
“没有产生新的决策”Agent或人员有没有做出任何决策日志里没有记录的选择？哪怕很小的决策也算
“架构没有变化，所以我跳过快照检查”没错——如果没有变更就不用更新，但要验证，不要假设
“技术债务太小了不需要登记”如果在验证阶段被注意到了就登记，未来的你会感谢现在的你
“我之后再更新文档”文档是收尾工作的一部分，现在不更新之后永远不会更新

Integration

集成说明

Called after:
  • pbs-pr-hardening (and pbs-review-fixes if needed) — when review report is resolved or clean
Required skills:
  • REQUIRED: superpowers:verification-before-completion — verify all docs are updated
Transitions:
  • If roadmap has more phases → pbs-phase-planning (for the next phase)
  • If roadmap is complete → END — project is done
Language: Write all 
.pbs-framework/
documents in the language defined in AGENTS.md 
framework_language
field.
调用时机：
  • pbs-pr-hardening（如有需要还要运行pbs-review-fixes）之后——审查报告已解决或无问题时
所需技能：
  • 必填： superpowers:verification-before-completion —— 验证所有文档已更新
流程流转：
  • 如果路线图还有更多阶段 → 调用pbs-phase-planning（为下一阶段做规划）
  • 如果路线图已完成 → 结束——项目完成
语言要求： 所有
.pbs-framework/
下的文档使用AGENTS.md中
framework_language
字段定义的语言编写。