Patrick Plate
136 lines
3.0 KiB
Markdown
136 lines
3.0 KiB
Markdown
---
|
|
name: generate-solution-doc
|
|
description: Solution documentation from implementation results.
|
|
---
|
|
|
|
# Skill: generate-solution-doc
|
|
|
|
Solution documentation from implementation results.
|
|
|
|
## Invoked by
|
|
|
|
📝 DocGen mode
|
|
|
|
## Required Inputs
|
|
|
|
| Input | Source | Example |
|
|
|-------|--------|---------|
|
|
| `TICKET_KEY` | Jira issue key | `PROJECT-123` |
|
|
| `MODULE` | Module/component name | `auth`, `api`, `core` |
|
|
| `PLAN_PATH` | Path to plan.md | `docs/auth/PROJECT-123/PROJECT-123-plan.md` |
|
|
| `TESTPLAN_PATH` | Path to testplan.md | `docs/auth/PROJECT-123/PROJECT-123-testplan.md` |
|
|
|
|
## Output
|
|
|
|
- Markdown: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md`
|
|
- PDF: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf`
|
|
|
|
## Steps
|
|
|
|
### 1. Read input documents
|
|
|
|
Read all available docs in `docs/<MODULE>/<TICKET_KEY>/`.
|
|
|
|
### 2. Analyze actual changes
|
|
|
|
```bash
|
|
cd <worktree-path>
|
|
git diff origin/main --stat
|
|
git diff origin/main --name-only
|
|
git log origin/main..HEAD --oneline
|
|
```
|
|
|
|
### 3. Gather test results
|
|
|
|
Check surefire reports or reference the testplan status.
|
|
|
|
### 4. Generate solution document
|
|
|
|
```markdown
|
|
# Solution Documentation: <TICKET_KEY>
|
|
|
|
**Date:** <today>
|
|
**Module:** <MODULE>
|
|
**Author:** <Your Name>
|
|
**Jira:** <TICKET_KEY>
|
|
**Branch:** <branch name>
|
|
|
|
---
|
|
|
|
## 1. Problem Statement
|
|
|
|
<What was the problem? Why did it need solving?>
|
|
|
|
## 2. Approach
|
|
|
|
<High-level approach chosen. Reference the plan document.>
|
|
|
|
## 3. Architecture Decisions
|
|
|
|
| Decision | Rationale | Alternatives |
|
|
|----------|----------|--------------|
|
|
| <decision> | <why> | <what was considered> |
|
|
|
|
## 4. Implemented Changes
|
|
|
|
### 4.1 <Component group>
|
|
|
|
| File | Change | Description |
|
|
|------|--------|-------------|
|
|
| `<path>` | New/Modified | <what changed> |
|
|
|
|
### 4.n Database Migrations
|
|
|
|
| Migration | Database | Description |
|
|
|-----------|----------|-------------|
|
|
| `V{timestamp}__...` | H2/Oracle | <what it does> |
|
|
|
|
## 5. Test Coverage
|
|
|
|
| ID | Description | Type | Result |
|
|
|----|-------------|------|--------|
|
|
| T-01 | <desc> | Unit | ✅ |
|
|
| T-02 | <desc> | Integration | ✅ |
|
|
|
|
## 6. Open Items
|
|
|
|
| # | Description | Priority | Ticket |
|
|
|---|-------------|----------|--------|
|
|
| 1 | <open item> | High/Medium/Low | <linked ticket or "—"> |
|
|
```
|
|
|
|
### 5. Ask for PDF color scheme
|
|
|
|
> "Which color scheme for the PDF? Available: adp (red), royal_purple, ocean, forest, sunset, slate, rose"
|
|
|
|
### 6. Generate PDF
|
|
|
|
```python
|
|
generate_pdf(
|
|
content=<markdown content>,
|
|
title=f"Solution Documentation {TICKET_KEY}",
|
|
author="Your Name",
|
|
output_path=f"docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf",
|
|
color_scheme=<chosen scheme>
|
|
)
|
|
```
|
|
|
|
### 7. Store in BigMind
|
|
|
|
```python
|
|
memory_store_fact(
|
|
category="codebase",
|
|
fact=f"{TICKET_KEY}: Solution doc created, PDF generated"
|
|
)
|
|
```
|
|
|
|
## Template Variants
|
|
|
|
### Minimal (for small bugfixes)
|
|
|
|
Skip sections 3 (Architecture Decisions) and 6 (Open Items). Keep 1, 2, 4, 5.
|
|
|
|
### Extended (for large features)
|
|
|
|
Add: Configuration Changes, Deployment Notes, Backward Compatibility, Performance Impact.
|