GSDL Document Decisions

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.

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
```
)

Step 1 — Gather Project Context

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)

Step 2 — Analyze Git History

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.

Step 3 — Extract Decisions and Changes

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

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

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)

Step 4 — Generate the Document

Write a structured markdown file to:

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

Use this format:

markdown

# [Project Name] — Decisions & Architecture

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

## Summary

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

## 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]

## 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]

## What Was Not Built

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

## 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

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.

Step 6 — Publish to Slite (if requested)

If the user provides a Slite URL or note ID:

Extract the Note 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

Method A — MCP (preferred)

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

Method 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]"
}

On Success

Report the created note's URL to the user:

✅ Published to Slite: [note URL]

On Failure

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

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

manually.

Step 7 — Publish to Notion (if requested)

If the user provides a Notion URL or page ID:

Extract the Page 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.

Method A — MCP (preferred)

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

Method 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
  ]
}

Markdown to Notion Block Conversion

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).

On Success

Report the created page's URL to the user:

✅ Published to Notion: [page URL]

On Failure

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

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

manually.

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")

gsdl-document-decisions

NPX Install

Tags

SKILL.md Content

GSDL Document Decisions

Inputs

Step 1 — Gather Project Context

Step 2 — Analyze Git History

Step 3 — Extract Decisions and Changes

Decisions

Architecture Changes

Step 4 — Generate the Document

Step 5 — Show Document Preview

Step 6 — Publish to Slite (if requested)

Extract the Note ID

Method A — MCP (preferred)

Method B — Slite REST API

On Success

On Failure

Step 7 — Publish to Notion (if requested)

Extract the Page ID

Method A — MCP (preferred)

Method B — Notion REST API

Markdown to Notion Block Conversion

On Success

On Failure

Rules