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:

1. [WORKSPACE_ROOT]/[PRD_PATH] — the original PRD (goals, requirements, non-goals)
2. [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.

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:

git show --stat [COMMIT_HASH]

Collect:

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

Also run:

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

where N 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:

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

1. Always save the markdown file first — even if the user skips publishing, the document must exist on disk
2. 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
3. Focus on decisions, not implementation details — the document is for future developers and stakeholders, not a code review
4. Keep the tone factual — describe what was done and why, avoid editorial commentary
5. If git history is ambiguous, note uncertainty rather than guessing (e.g., "library choice not evident from commits — see PRD for context")