gsdl-document-decisions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GSDL Document Decisions

GSDL 决策文档

Analyzes what was built during a GSDL project, captures the key decisions and architecture changes, saves them to a markdown file, and optionally publishes to Slite or Notion.

分析GSDL项目中构建的内容，捕获关键决策和架构变更，将其保存为Markdown文件，还可选择发布到Slite或Notion。

Inputs

输入参数

```
PROJECT_NAME
```
— the project name (kebab-case)
```
WORKSPACE_ROOT
```
— absolute path to workspace root
```
PRD_PATH
```
— relative path to the PRD file (from
```
progress.md
```
)
```
TASKS_PATH
```
— relative path to the task list file (from
```
progress.md
```
)

```
PROJECT_NAME
```
— 项目名称（短横线分隔格式，kebab-case）
```
WORKSPACE_ROOT
```
— 工作区根目录的绝对路径
```
PRD_PATH
```
— PRD文件的相对路径（相对于
```
progress.md
```
）
```
TASKS_PATH
```
— 任务列表文件的相对路径（相对于
```
progress.md
```
）

Step 1 — Gather Project Context

步骤1 — 收集项目上下文

Read the following files from disk:

```
[WORKSPACE_ROOT]/[PRD_PATH]
```
— the original PRD (goals, requirements, non-goals)
```
[WORKSPACE_ROOT]/[TASKS_PATH]
```
— the completed task list (what was planned and built)

从磁盘读取以下文件：

```
[WORKSPACE_ROOT]/[PRD_PATH]
```
— 原始PRD（目标、需求、非目标）
```
[WORKSPACE_ROOT]/[TASKS_PATH]
```
— 已完成的任务列表（计划和实际构建的内容）

Step 2 — Analyze Git History

步骤2 — 分析Git历史记录

Run the following to get commits made during this project. Use the task list to estimate the date range (oldest unchecked task → most recent commit), or simply retrieve all commits from the first

gsdl

commit for this project onward.

bash

git log --oneline --no-merges

Then for each commit that is part of this project (identified by the

[N.0]

prefix in the commit message or by matching the project's parent task titles), run:

bash

git show --stat [COMMIT_HASH]

Collect:

Commit messages and their bullet points
Files created, modified, or deleted

Also run:

bash

git diff HEAD~[N] HEAD --name-status

where

is the number of project commits, to get the full file-change summary across the entire project.

运行以下命令获取项目期间的提交记录。使用任务列表估算日期范围（最早的未勾选任务 → 最新的提交），或者直接获取该项目第一个

gsdl

提交之后的所有提交。

bash

git log --oneline --no-merges

然后对于每个属于该项目的提交（通过提交消息中的

[N.0]

前缀或匹配项目的父任务标题识别），运行：

bash

git show --stat [COMMIT_HASH]

收集:

提交消息及其要点
创建、修改或删除的文件

同时运行:

bash

git diff HEAD~[N] HEAD --name-status

其中

是项目提交的数量，用于获取整个项目期间的完整文件变更摘要。

Step 3 — Extract Decisions and Changes

步骤3 — 提取决策与变更

Using the PRD, task list, commit messages, and file diffs, synthesize the following:

利用PRD、任务列表、提交消息和文件差异，整理以下内容：

Decisions

决策

Identify decisions made during implementation that deviate from or elaborate on the PRD, or that represent a meaningful architectural/design choice. Look for:

Libraries or frameworks chosen (and why, if evident from commit messages or code)
Patterns adopted (e.g., "used repository pattern", "chose REST over GraphQL")
Trade-offs or constraints honored
Things explicitly NOT done (non-goals honored, scope cuts)
Any tasks that were modified, added, or skipped during execution

识别在实施过程中做出的、偏离或细化PRD的决策，或者具有重要意义的架构/设计选择。重点关注：

选择的库或框架（如果从提交消息或代码中能看出原因，一并记录）
采用的模式（例如："使用仓库模式"、"选择REST而非GraphQL"）
权衡或遵循的约束
明确未做的事项（遵循的非目标、范围缩减）
执行期间修改、添加或跳过的任何任务

Architecture Changes

架构变更

Identify structural changes to the codebase:

New directories or modules created
New dependencies added (check
```
package.json
```
,
```
requirements.txt
```
,
```
go.mod
```
, etc.)
New configuration files introduced
Significant refactors to existing structure
Integration points added (APIs, services, databases)

识别代码库的结构性变更：

创建的新目录或模块
添加的新依赖（检查
```
package.json
```
、
```
requirements.txt
```
、
```
go.mod
```
等）
引入的新配置文件
对现有结构的重大重构
添加的集成点（API、服务、数据库）

Step 4 — Generate the Document

步骤4 — 生成文档

Write a structured markdown file to:

[WORKSPACE_ROOT]/.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

Use this format:

markdown

undefined

将结构化的Markdown文件写入：

[WORKSPACE_ROOT]/.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

使用以下格式：

markdown

undefined

[Project Name] — Decisions & Architecture

[项目名称] — 决策与架构

Generated by GSDL on [YYYY-MM-DD] PRD: [prd file name] Tasks: [tasks file name]

由GSDL生成于 [YYYY-MM-DD] PRD: [prd文件名] 任务: [任务文件名]

Summary

摘要

[2–4 sentences describing what was built, the core approach taken, and any major constraints honored.]

[2-4句话描述构建的内容、采用的核心方法以及遵循的主要约束。]

Key Decisions

关键决策

[Decision Title]

[决策标题]

What: [What was decided] Why: [Rationale, if evident from code/commits/PRD] Impact: [Files, modules, or behaviors affected]

[Repeat for each significant decision — aim for 3–8 decisions]

内容: [做出的决策内容] 原因: [依据，若从代码/提交/PRD中可得知] 影响: [受影响的文件、模块或行为]

[重复记录每个重要决策 — 目标3-8个决策]

Architecture Changes

架构变更

New Structure

新结构

[Bulleted list of new directories, modules, or files created with one-line descriptions]

[新创建的目录、模块或文件的项目符号列表，附带一行描述]

Dependencies Added

添加的依赖

[Bulleted list of new packages/libraries added, with purpose]

[新增的包/库的项目符号列表，附带用途说明]

Integration Points

集成点

[Any new APIs, services, databases, or external integrations introduced]

[引入的任何新API、服务、数据库或外部集成]

What Was Not Built

未构建的内容

[Bulleted list of PRD requirements or tasks explicitly skipped or deferred, with brief reason if known]

[PRD需求或明确跳过/推迟的任务的项目符号列表，若已知原因则简要说明]

Files Changed

文件变更

File	Change
[path]	Created / Modified / Deleted

[Table listing all files changed during the project, sorted by most significant first]


Omit sections that have no content (e.g., if no dependencies were added, omit "Dependencies Added").

---

文件	变更类型
[路径]	创建 / 修改 / 删除

[列出项目期间所有变更的文件表格，按重要性排序]


省略没有内容的章节（例如：如果没有添加依赖，省略"添加的依赖"章节）。

---

Step 5 — Show Document Preview

步骤5 — 显示文档预览

Display the generated document to the user and say:

✅ Decisions document saved to: .planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

Would you like to publish this to Slite or Notion?
- Type "slite [URL or note ID]" to publish as a child doc in Slite
- Type "notion [URL or page ID]" to publish as a child page in Notion
- Type "no" or press Enter to skip

Paste the URL of the parent doc/page where this should live, or skip.

向用户展示生成的文档，并提示：

✅ 决策文档已保存至: .planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

是否要将其发布到Slite或Notion？
- 输入 "slite [URL或笔记ID]" 以在Slite中发布为子文档
- 输入 "notion [URL或页面ID]" 以在Notion中发布为子页面
- 输入 "no" 或按回车键跳过

请粘贴要存放此文档的父文档/页面的URL，或直接跳过。

Step 6 — Publish to Slite (if requested)

步骤6 — 发布到Slite（若用户要求）

If the user provides a Slite URL or note ID:

如果用户提供了Slite URL或笔记ID：

Extract the Note ID

提取笔记ID

URL formats:

https://slite.com/app/docs/{NOTE_ID}/{title}

— extract

NOTE_ID

after

/docs/

https://{workspace}.slite.com/p/{NOTE_ID}/{title}

— extract

NOTE_ID

after

/p/

https://slite.com/p/{NOTE_ID}/{title}

— extract

NOTE_ID

after

/p/

Bare note ID (no URL prefix) — use directly

URL格式：

https://slite.com/app/docs/{NOTE_ID}/{title}

— 提取

/docs/

后的

NOTE_ID

https://{workspace}.slite.com/p/{NOTE_ID}/{title}

— 提取

/p/

后的

NOTE_ID

https://slite.com/p/{NOTE_ID}/{title}

— 提取

/p/

后的

NOTE_ID

纯笔记ID（无URL前缀） — 直接使用

Method A — MCP (preferred)

方法A — MCP（优先选择）

Check if a Slite MCP server is configured:

Look in
```
~/.cursor/mcp.json
```
or
```
.cursor/mcp.json
```
for a server with
```
slite
```
in the name or command
If found, use
```
create-note
```
with:
- ```
title
```
  :
```
[Project Name] — Decisions & Architecture
```
- ```
parentNoteId
```
  : the extracted note ID
- ```
markdown
```
  : the full content of the generated document

检查是否配置了Slite MCP服务器：

在
```
~/.cursor/mcp.json
```
或
```
.cursor/mcp.json
```
中查找名称或命令包含
```
slite
```
的服务器
如果找到，使用
```
create-note
```
接口，参数如下：
- ```
title
```
  :
```
[项目名称] — 决策与架构
```
- ```
parentNoteId
```
  : 提取的笔记ID
- ```
markdown
```
  : 生成的文档完整内容

Method B — Slite REST API

方法B — Slite REST API

If MCP is not available, check for

$SLITE_API_KEY

environment variable.

POST https://api.slite.com/v1/notes
Authorization: Bearer $SLITE_API_KEY
Content-Type: application/json

{
  "title": "[Project Name] — Decisions & Architecture",
  "parentNoteId": "[PARENT_NOTE_ID]",
  "markdown": "[document content]"
}

如果MCP不可用，检查是否存在

$SLITE_API_KEY

环境变量。

POST https://api.slite.com/v1/notes
Authorization: Bearer $SLITE_API_KEY
Content-Type: application/json

{
  "title": "[Project Name] — Decisions & Architecture",
  "parentNoteId": "[PARENT_NOTE_ID]",
  "markdown": "[document content]"
}

On Success

成功时

Report the created note's URL to the user:

✅ Published to Slite: [note URL]

向用户报告创建的笔记URL：

✅ 已发布至Slite: [笔记URL]

On Failure

失败时

Tell the user what failed and suggest they copy the markdown from

.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

manually.

告知用户失败原因，并建议他们手动从

.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

复制Markdown内容。

Step 7 — Publish to Notion (if requested)

步骤7 — 发布到Notion（若用户要求）

If the user provides a Notion URL or page ID:

如果用户提供了Notion URL或页面ID：

Extract the Page ID

提取页面ID

URL formats:

https://www.notion.so/{workspace}/{Page-Title}-{PAGE_ID}

— extract the 32-char hex suffix

```
https://www.notion.so/{PAGE_ID}
```
— use directly

https://{workspace}.notion.site/{Page-Title}-{PAGE_ID}

— extract the 32-char hex suffix

Bare page ID — use directly

Normalize by removing hyphens if present.

URL格式：

https://www.notion.so/{workspace}/{Page-Title}-{PAGE_ID}

— 提取32位十六进制后缀

```
https://www.notion.so/{PAGE_ID}
```
— 直接使用

https://{workspace}.notion.site/{Page-Title}-{PAGE_ID}

— 提取32位十六进制后缀

纯页面ID — 直接使用

如果存在连字符，移除后标准化。

Method A — MCP (preferred)

方法A — MCP（优先选择）

Check if a Notion MCP server is configured:

Look in
```
~/.cursor/mcp.json
```
or
```
.cursor/mcp.json
```
for a server with
```
notion
```
in the name or command
If found, use the appropriate MCP tool to create a child page:
- Parent: the extracted page ID
- Title:
```
[Project Name] — Decisions & Architecture
```
- Content: the full markdown document

检查是否配置了Notion MCP服务器：

在
```
~/.cursor/mcp.json
```
或
```
.cursor/mcp.json
```
中查找名称或命令包含
```
notion
```
的服务器
如果找到，使用适当的MCP工具创建子页面：
- 父页面: 提取的页面ID
- 标题:
```
[项目名称] — 决策与架构
```
- 内容: 完整的Markdown文档

Method B — Notion REST API

方法B — Notion REST API

If MCP is not available, check for

$NOTION_TOKEN

environment variable.

Create a new child page:

POST https://api.notion.com/v1/pages
Authorization: Bearer $NOTION_TOKEN
Notion-Version: 2022-06-28
Content-Type: application/json

{
  "parent": { "page_id": "[PARENT_PAGE_ID]" },
  "properties": {
    "title": {
      "title": [{ "text": { "content": "[Project Name] — Decisions & Architecture" } }]
    }
  },
  "children": [
    // Convert the markdown document into Notion block objects
    // Map headings → heading_2/heading_3 blocks
    // Map paragraphs → paragraph blocks
    // Map bullet lists → bulleted_list_item blocks
    // Map tables → table blocks
    // Map bold text → rich_text with bold annotation
  ]
}

如果MCP不可用，检查是否存在

$NOTION_TOKEN

环境变量。

创建新的子页面：

POST https://api.notion.com/v1/pages
Authorization: Bearer $NOTION_TOKEN
Notion-Version: 2022-06-28
Content-Type: application/json

{
  "parent": { "page_id": "[PARENT_PAGE_ID]" },
  "properties": {
    "title": {
      "title": [{ "text": { "content": "[Project Name] — Decisions & Architecture" } }]
    }
  },
  "children": [
    // 将Markdown文档转换为Notion块对象
    // 映射标题 → heading_2/heading_3块
    // 映射段落 → paragraph块
    // 映射项目符号列表 → bulleted_list_item块
    // 映射表格 → table块
    // 映射粗体文本 → 带有bold注解的rich_text
  ]
}

Markdown to Notion Block Conversion

Markdown到Notion块的转换

Convert the document sections as follows:

Markdown	Notion Block Type
`# Heading`	`heading_1`
`## Heading`	`heading_2`
`### Heading`	`heading_3`
`> blockquote`	`quote`
`- bullet item`	`bulleted_list_item`
Regular paragraph	`paragraph`
`	table
`bold`	`rich_text` with `bold: true` annotation

Keep each text block under 2000 characters (Notion's limit per rich_text object).

按以下方式转换文档章节：

Markdown	Notion块类型
`# Heading`	`heading_1`
`## Heading`	`heading_2`
`### Heading`	`heading_3`
`> blockquote`	`quote`
`- bullet item`	`bulleted_list_item`
普通段落	`paragraph`
`	table
`bold`	带有 `bold: true` 注解的 `rich_text`

每个文本块保持在2000字符以内（Notion的每个rich_text对象限制）。

On Success

成功时

Report the created page's URL to the user:

✅ Published to Notion: [page URL]

向用户报告创建的页面URL：

✅ 已发布至Notion: [页面URL]

On Failure

失败时

Tell the user what failed and suggest they copy the markdown from

.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

manually.

告知用户失败原因，并建议他们手动从

.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

复制Markdown内容。

Rules

规则

Always save the markdown file first — even if the user skips publishing, the document must exist on disk

Never overwrite an existing decisions file — if

.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

already exists, append a timestamp suffix:

decisions-[PROJECT_NAME]-[YYYYMMDD].md

Focus on decisions, not implementation details — the document is for future developers and stakeholders, not a code review
Keep the tone factual — describe what was done and why, avoid editorial commentary
If git history is ambiguous, note uncertainty rather than guessing (e.g., "library choice not evident from commits — see PRD for context")

始终先保存Markdown文件 — 即使用户跳过发布，文档也必须存在于磁盘上

绝不覆盖现有决策文件 — 如果

.planning/[PROJECT_NAME]/decisions-[PROJECT_NAME].md

已存在，添加时间戳后缀：

decisions-[PROJECT_NAME]-[YYYYMMDD].md

聚焦决策，而非实现细节 — 文档面向未来的开发人员和利益相关者，而非代码评审
保持语气客观 — 描述做了什么以及原因，避免主观评论
如果Git历史记录不明确 — 记录不确定性而非猜测（例如："从提交中无法看出库的选择原因 — 请查看PRD了解上下文"）