Tutorial Overview
Series index: gstack Tutorial Series
After shipping, close the loop: /document-release updates docs, /retro reflects on what worked, /learn captures patterns for next time.
What you will learn
- ✅
/document-releasedocumentation sync - ✅ Stale doc detection
- ✅
/retroweekly engineering retrospective - ✅ Per-person breakdowns and trends
- ✅
/learnmemory management - ✅ After-shipping workflow
Why Post-Release Documentation?
The doc drift problem
flowchart LR
A[Code Changes] --> B[Docs Not Updated]
B --> C[New Developer Confused]
C --> D[Wrong Assumptions]
D --> E[Bugs]
style B fill:#ffcccc
style E fill:#ffcccc
/document-release solution
flowchart TD
A[/document-release] --> B[Scan Changed Files]
B --> C[Find Related Docs]
C --> D[Detect Drift]
D --> E[Update Docs]
E --> F[Commit Changes]
style A fill:#e1f5ff
style F fill:#e8f5e9
/document-release — Sync Docs to Code
What it updates
| File | When Updated |
|---|---|
| README.md | New features, setup changes, new commands |
| ARCHITECTURE.md | Structural changes, new modules |
| CONTRIBUTING.md | New workflows, changed prerequisites |
| CLAUDE.md | AI context changes, new patterns |
| API.md | New endpoints, changed parameters |
| CHANGELOG.md | Every release |
Usage
/document-release
Output:
Scanning for documentation drift...
┌─────────────────────────────────────────────────────────────┐
│ DOCUMENT RELEASE │
├─────────────────────────────────────────────────────────────┤
│ Changed files: 12 │
│ Related docs: 4 │
│ │
│ 📄 README.md │
│ ─────────────────────────────────────────────────────────────│
│ Section: Getting Started │
│ Issue: References old package name │
│ │
│ Old: npm install mypkg-v1 │
│ New: npm install mypkg-v2 │
│ │
│ 🔧 Updated │
│ │
│ 📄 ARCHITECTURE.md │
│ ─────────────────────────────────────────────────────────────│
│ Section: Module Overview │
│ Issue: Missing new auth module │
│ │
│ Added: │
│ - src/auth/ - Authentication system (new) │
│ - login.ts - Login flow │
│ - session.ts - Session management │
│ │
│ 🔧 Updated │
│ │
│ 📄 CHANGELOG.md │
│ ─────────────────────────────────────────────────────────────│
│ Added entry: │
│ │
│ ## 2026-04-07 - v2.1.0 │
│ │
│ ### Added │
│ - Authentication system with OAuth2 support │
│ - Session management with secure cookies │
│ │
│ ### Changed │
│ - Updated package from v1 to v2 │
│ │
│ 🔧 Updated │
│ │
│ 📄 CLAUDE.md │
│ ─────────────────────────────────────────────────────────────│
│ Issue: Missing auth patterns │
│ │
│ Added: │
│ - Auth flow: Use /login endpoint, not /auth │
│ - Sessions: Always check before API calls │
│ - Testing: Mock session in tests with mockSession() │
│ │
│ 🔧 Updated │
└─────────────────────────────────────────────────────────────┘
Documentation updated: 4 files
Commit: docs: update documentation for v2.1.0
Stale doc detection
Detects when docs don’t match code:
| Check | Detection |
|---|---|
| Outdated commands | Command references removed code |
| Missing modules | New directory not documented |
| Wrong file paths | Renamed files still referenced |
| Deprecated APIs | Still documented as current |
| Wrong examples | Example code doesn’t match reality |
What gets scanned
project/
├── README.md ✅ Always scanned
├── ARCHITECTURE.md ✅ Always scanned
├── CONTRIBUTING.md ✅ Always scanned
├── CLAUDE.md ✅ Always scanned
├── docs/
│ ├── API.md ✅ If exists
│ ├── SETUP.md ✅ If exists
│ └── DEPLOY.md ✅ If exists
└── CHANGELOG.md ✅ Always updated
/retro — Engineering Retrospective
What it analyzes
- Commits since last retro
- PRs merged
- Tests added/removed
- Bugs fixed
- Performance changes
Usage
/retro
Output:
Running engineering retrospective...
┌─────────────────────────────────────────────────────────────┐
│ WEEKLY RETROSPECTIVE │
│ Period: 2026-03-31 to 2026-04-07 │
├─────────────────────────────────────────────────────────────┤
│ 📊 SUMMARY │
│ ─────────────────────────────────────────────────────────────│
│ Commits: 47 │
│ PRs merged: 12 │
│ Tests added: 34 │
│ Bugs fixed: 8 │
│ Coverage: 78% → 82% (+4%) │
│ │
│ 📊 PER-PERSON BREAKDOWN │
│ ─────────────────────────────────────────────────────────────│
│ @alice │
│ Commits: 18 │
│ PRs: 5 │
│ Tests: 15 │
│ Shipping streak: 12 days │
│ Focus: Authentication system │
│ │
│ @bob │
│ Commits: 15 │
│ PRs: 4 │
│ Tests: 12 │
│ Shipping streak: 8 days │
│ Focus: API optimization │
│ │
│ @charlie │
│ Commits: 14 │
│ PRs: 3 │
│ Tests: 7 │
│ Shipping streak: 5 days │
│ Focus: Bug fixes and QA │
│ │
│ 📊 TEST HEALTH TRENDS │
│ ─────────────────────────────────────────────────────────────│
│ Coverage trend: ↑ +4% │
│ Flaky tests: 2 (down from 5) │
│ Test runtime: 45s (down from 52s) │
│ │
│ 📊 WHAT WENT WELL │
│ ─────────────────────────────────────────────────────────────│
│ ✅ Auth system shipped on time │
│ ✅ Coverage improved 4% │
│ ✅ Zero production incidents │
│ ✅ PR review time: avg 4 hours │
│ │
│ 📊 WHAT TO IMPROVE │
│ ─────────────────────────────────────────────────────────────│
│ ⚠️ 2 flaky tests remaining │
│ ⚠️ API response time +5% on dashboard │
│ ⚠️ Missing tests for error paths │
│ │
│ 📊 ACTION ITEMS │
│ ─────────────────────────────────────────────────────────────│
│ 1. Fix flaky tests (auth.test.ts, api.test.ts) │
│ 2. Profile dashboard API performance │
│ 3. Add error path tests (target: 85% coverage) │
└─────────────────────────────────────────────────────────────┘
Retro saved: .gstack/retros/2026-04-07.md
Global retrospective
Run across all projects:
/retro global
Output:
Running global retrospective across all projects...
┌─────────────────────────────────────────────────────────────┐
│ GLOBAL RETROSPECTIVE │
│ Projects: 4 | Period: Last 7 days │
├─────────────────────────────────────────────────────────────┤
│ 📊 CROSS-PROJECT STATS │
│ ─────────────────────────────────────────────────────────────│
│ Total commits: 142 │
│ Total PRs: 38 │
│ Total tests added: 89 │
│ Projects with coverage >80%: 3/4 │
│ │
│ 📊 BY PROJECT │
│ ─────────────────────────────────────────────────────────────│
│ myapp: 47 commits, 82% coverage │
│ api-server: 52 commits, 85% coverage │
│ dashboard: 28 commits, 75% coverage ⚠️ │
│ mobile-app: 15 commits, 88% coverage │
│ │
│ 📊 AI TOOL USAGE │
│ ─────────────────────────────────────────────────────────────│
│ Claude Code sessions: 156 │
│ Codex calls: 42 │
│ /review runs: 28 │
│ /qa runs: 15 │
│ │
│ ⚠️ ATTENTION NEEDED │
│ ─────────────────────────────────────────────────────────────│
│ dashboard: Coverage below 80% │
│ Run: cd dashboard && /ship │
└─────────────────────────────────────────────────────────────┘
/learn — Memory Management
What it stores
| Category | Examples |
|---|---|
| Patterns | “Always use zod for API validation” |
| Pitfalls | “Don’t use useEffect without deps array” |
| Preferences | “Use Tailwind over CSS modules” |
| Conventions | “API routes go in src/api/” |
| Gotchas | “Environment variables need NEXT_PUBLIC_ prefix” |
Usage
Add learning
/learn pattern: "Always validate API inputs with zod before processing"
Query learning
/learn ask "What's our validation pattern?"
Output:
Querying learned knowledge...
┌─────────────────────────────────────────────────────────────┐
│ LEARNED KNOWLEDGE │
├─────────────────────────────────────────────────────────────┤
│ Pattern: API Validation │
│ ─────────────────────────────────────────────────────────────│
│ "Always validate API inputs with zod before processing" │
│ │
│ Related: │
│ - Pitfall: "Never trust request.body without validation" │
│ - Convention: "Validation schemas go in src/schemas/" │
│ - Pattern: "Use .parse() for throw, .safeParse() for check" │
│ │
│ Added: 2026-03-15 │
│ Used: 12 times │
└─────────────────────────────────────────────────────────────┘
List all learnings
/learn list
Output:
Listing all learned knowledge...
┌─────────────────────────────────────────────────────────────┐
│ LEARNED KNOWLEDGE (15 items) │
├─────────────────────────────────────────────────────────────┤
│ PATTERNS (6) │
│ ─────────────────────────────────────────────────────────────│
│ 1. API validation with zod │
│ 2. Error handling with Result type │
│ 3. React Query for data fetching │
│ 4. Tailwind for styling │
│ 5. TypeScript strict mode │
│ 6. Atomic commits for each fix │
│ │
│ PITFALLS (5) │
│ ─────────────────────────────────────────────────────────────│
│ 1. useEffect without deps array │
│ 2. Storing secrets in client code │
│ 3. Direct DOM manipulation in React │
│ 4. Unvalidated environment variables │
│ 5. Sync operations in async functions │
│ │
│ CONVENTIONS (4) │
│ ─────────────────────────────────────────────────────────────│
│ 1. API routes: src/api/ │
│ 2. Components: src/components/ │
│ 3. Tests: tests/ mirror structure │
│ 4. PR title: type: description │
└─────────────────────────────────────────────────────────────┘
When /learn auto-triggers
- After fixing a recurring bug → Adds pitfall
- After establishing a pattern → Adds pattern
- After PR review feedback → Adds convention
- After
/retroaction items → Adds todo
After-Shipping Workflow
Complete sequence
flowchart TD
A[/land-and-deploy] --> B[/canary]
B --> C[/benchmark]
C --> D[/document-release]
D --> E[/retro]
E --> F[/learn]
F --> G[Done]
style A fill:#e8f5e9
style D fill:#fff3e0
style G fill:#e1f5ff
Commands
# 1. Document what shipped
/document-release
# 2. Run retrospective
/retro
# 3. Capture learnings from the week
/learn list # Review current knowledge
# 4. Add any new patterns discovered
/learn pattern: "New pattern discovered during release"
# 5. Ready for next sprint
Example: Post-Release Workflow
Scenario
Just shipped v2.1.0 with auth system.
Commands
# Step 1: Update documentation
/document-release
# Step 2: Run retro
/retro
# Step 3: Capture learnings
/learn pattern: "Auth: Use httpOnly cookies for session tokens"
/learn pitfall: "Don't store session in localStorage (XSS risk)"
# Step 4: Check global health
/retro global
Output from retro
RETROSPECTIVE ACTION ITEMS:
1. Fix flaky auth tests
2. Add dashboard performance profiling
3. Increase coverage to 85%
Run these before next release:
- /qa --focus auth
- /benchmark --compare
Skill Quick Reference
| Command | Purpose | Output |
|---|---|---|
/document-release |
Sync docs to code | Updated docs, commit |
/retro |
Weekly retro | Stats, breakdowns, actions |
/retro global |
All projects retro | Cross-project health |
/learn add <type> <text> |
Add knowledge | Stored in memory |
/learn ask <question> |
Query knowledge | Related learnings |
/learn list |
Show all | Categorized list |
Summary
Post-release skills in gstack provide:
- Doc sync — Keep docs matching code
- Stale detection — Find outdated references
- Retrospectives — Weekly reflection with data
- Per-person stats — Track contributions
- Memory management — Capture patterns for future
Key takeaways
- ✅ Run
/document-releaseafter every deploy - ✅ Run
/retroweekly (Fridays recommended) - ✅ Add learnings as you discover patterns
- ✅ Use
/retro globalfor multi-project view
Series navigation:
- ← Previous: Tutorial 10: Release Engineering
- → Next: Tutorial 12: Parallel Sprints
- Back: Series Index