RFC: Knowledge Distillation — Evolving /gsd:pr-branch from Filtering to Synthesis

[alexpalyan]

Context

The current implementation of /gsd:pr-branch focuses exclusively on filtering: it removes transient planning artifacts (phases/, research/, todos/) to clean up the Pull Request from AI "noise."

While effective for noise reduction, this creates two critical issues for the project lifecycle:

1. The Broken Link Problem: Structural files that remain (ROADMAP.md, STATE.md) often contain numerous links to the deleted transient files (PLAN.md, SUMMARY.md), leaving the repository with "invalid" documentation.
2. Knowledge Siloing: The most valuable insights gained during a phase (architectural decisions, research findings, implementation trade-offs) are deleted along with the transient files, never reaching the project’s permanent documentation (docs/).

Proposal: The Distillation Pattern

We propose evolving /gsd:pr-branch from a simple filter into a knowledge compiler. Instead of just deleting files, the tool should distill the essence of the .planning/ artifacts into self-contained, human-readable documentation in the docs/ directory before cleaning the branch.

1. Scratchpad vs. Final Report

• Source: .planning/ remains the AI’s private "scratchpad" for rapid state updates and transient thoughts.
• Target: docs/ becomes the public, high-signal interface for human developers and reviewers.

2. Artifact Mapping & Synthesis

We suggest a mapping where GSD artifacts are synthesized into standard documentation formats:

GSD Artifact (.planning/)	Distillation Process	Resulting Doc (docs/)
PROJECT.md / REQUIREMENTS.md	Direct Export / Sync	docs/VISION.md / docs/PRD.md
codebase/ (Explore maps)	Aggregate into a cohesive overview	docs/ARCHITECTURE.md
phases/*/CONTEXT.md & RESEARCH.md	Extract key decisions and constraints	docs/adr/XXXX-name.md (ADR)
phases/*/SUMMARY.md	Aggregate and summarize work performed	docs/CHANGELOG.md
ROADMAP.md	Sanitize: replace broken links with text statuses	docs/ROADMAP.md (Human-readable)

3. Link Sanitization

The tool should automatically rewrite Markdown links during synthesis. For example:
[Plan](.planning/phases/01-auth/PLAN.md) ➡️ [Phase 01: Auth (Completed)].

Benefits for Solo Developers

• Zero-Effort Documentation: High-quality project documentation becomes a byproduct of the development process, not an extra chore.
• High-Signal PRs: Reviewers see updated architecture and clear ADRs instead of raw planning noise.
• Project Longevity: Project knowledge survives in standard docs/ format even if the GSD tooling is not present.
• Closing the Loop: This complements feat(plan-phase): --ingest <adr-path> flag — synthesize PLAN.md from Architectural Decision Records #3209 (ingest ADRs), creating a bidirectional bridge between planning and documentation.

Implementation Path

This could be implemented as a new step in the pr-branch workflow or as a pre-hook for /gsd:ship. It would leverage the gsd-sdk to handle the extraction and templating logic.

We believe this shift from "hiding AI tracks" to "AI reporting to humans" is a vital step in the evolution of agentic development workflows.