diff --git a/Change-V04.1.0%3A-Proposal.md b/Change-V04.1.0%3A-Proposal.md new file mode 100644 index 0000000..08539e0 --- /dev/null +++ b/Change-V04.1.0%3A-Proposal.md @@ -0,0 +1,273 @@ +> **Type:** Change Proposal +> **Version:** V04.1.0 +> **Plugin:** projman +> **Status:** In Progress +> **Date:** 2026-01-25 + +--- + +# Wiki-Based Planning Workflow Enhancement + +## Problem Statement + +Currently, projman's sprint planning workflow has these limitations: + +1. **Confusion between planning docs and documentation** - Planning documents in `docs/changes/` can be confused with regular project documentation +2. **Lost planning context** - Once issues are created, the original planning rationale may be lost or disconnected +3. **No iteration tracking** - When a feature requires multiple attempts, there's no structured way to track each implementation +4. **Fragmented audit trail** - The path from idea → planning → implementation → lessons is not clearly linked + +## Proposed Solution + +Integrate wiki-based change proposals into the projman workflow, creating a structured system for tracking planning documents separately from regular documentation. + +### Wiki Structure + +``` +wiki/ +├── lessons-learned/ +│ └── sprints/ # Existing +│ ├── sprint-17.md +│ └── sprint-18.md +└── changes/ # NEW + └── v04.0.0/ + ├── proposal.md + └── implementation-1.md + └── v04.1.0/ + ├── proposal.md + └── implementation-1.md +``` + +### Page Naming Convention + +| Type | Pattern | Example | +|------|---------|---------| +| Proposal | `Change VXX.X.X: Proposal` | Change V04.0.0: Proposal | +| Implementation | `Change VXX.X.X: Proposal (Implementation N)` | Change V04.1.0: Proposal (Implementation 1) | +| Internal Work | `Change Sprint-NN: Proposal` | Change Sprint-17: Proposal | + +### Tagging System + +**For Proposals:** +```markdown +> **Type:** Change Proposal +> **Version:** VXX.X.X +> **Plugin:** plugin-name (optional) +> **Status:** Pending | In Progress | Implemented | Abandoned +> **Date:** YYYY-MM-DD + +## Implementations +- [Implementation 1](link) - description +``` + +**For Implementations:** +```markdown +> **Type:** Change Proposal Implementation +> **Version:** VXX.X.X +> **Status:** In Progress | Implemented | Failed +> **Date:** YYYY-MM-DD +> **Origin:** [Proposal Link](link) +> **Sprint:** Sprint XX (optional) +``` + +## Input Document Format + +Standardized frontmatter for local input files (`docs/changes/*.md`): + +```yaml +--- +version: "4.1.0" # or "sprint-17" for internal work +title: "Wiki-Based Planning Workflow" +plugin: projman # optional, for plugin-specific changes +type: feature # feature | bugfix | refactor | infra +--- + +# Feature Description + +[Free-form content describing what you want to build...] +``` + +## Flexible Input Sources + +| Source | Description | What `/sprint-plan` does | +|--------|-------------|--------------------------| +| **Local file** | `docs/changes/v4.1.0-feature.md` | Parse, migrate to wiki, delete local | +| **Conversation** | Discussion with Claude leads to plan | Create wiki pages from conversation context | +| **Existing wiki** | User already created wiki proposal | Skip creation, proceed to implementation page | + +### Input Detection Logic + +``` +IF docs/changes/*.md exists: + → Use local file (migrate to wiki, then delete) + +ELSE IF wiki "Change VXX.X.X: Proposal" exists: + → Use existing wiki (add new implementation) + +ELSE IF conversation contains planning context: + → Ask user to confirm version/title + → Create proposal from conversation + +ELSE: + → Ask user: "What are we planning?" +``` + +## Enhanced Workflow + +### /sprint-plan (Enhanced) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 1. VALIDATION (existing) │ +│ - Check branch (development) │ +│ - Validate repo/org configuration │ +│ - Sync labels if needed │ +├─────────────────────────────────────────────────────────────────┤ +│ 2. DETERMINE INPUT SOURCE (new) │ +│ - Check for docs/changes/*.md files │ +│ - Check for existing wiki proposal (by version) │ +│ - If neither: use current conversation context │ +│ │ +│ ASK USER if ambiguous: │ +│ "I found [X]. Should I use this as the planning input?" │ +├─────────────────────────────────────────────────────────────────┤ +│ 3. SEARCH LESSONS LEARNED (existing) │ +│ - Query wiki for relevant past lessons │ +│ - Surface applicable patterns/warnings │ +├─────────────────────────────────────────────────────────────────┤ +│ 4. CREATE/UPDATE WIKI PROPOSAL (conditional) │ +│ - IF local file: migrate content, delete file │ +│ - IF conversation: create from discussion │ +│ - IF existing wiki: skip, use as-is │ +├─────────────────────────────────────────────────────────────────┤ +│ 5. CREATE WIKI IMPLEMENTATION PAGE (new) │ +│ - Determine implementation number (N) │ +│ - Create "Change V04.1.0: Proposal (Implementation N)" │ +│ - Content: migrated from input document │ +│ - Tags: Type, Version, Status=In Progress, Date, Origin │ +│ - Update proposal page with link to this implementation │ +├─────────────────────────────────────────────────────────────────┤ +│ 6. ARCHITECTURE ANALYSIS (existing) │ +│ - Analyze codebase │ +│ - Ask clarifying questions │ +│ - Identify affected files │ +├─────────────────────────────────────────────────────────────────┤ +│ 7. CREATE GITEA ISSUES (existing, enhanced) │ +│ - Create issues for each task │ +│ - ADD: wiki implementation reference in description │ +│ "Implementation: [Change V04.1.0 (Impl 1)](wiki-link)" │ +├─────────────────────────────────────────────────────────────────┤ +│ 8. CLEANUP (new) │ +│ - Delete local input file (docs/changes/v4.1.0-*.md) │ +│ - Wiki is now single source of truth │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### /sprint-close (Enhanced) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 1. VERIFY ISSUES CLOSED (existing) │ +│ - Check all milestone issues are closed │ +│ - Warn if any remain open │ +├─────────────────────────────────────────────────────────────────┤ +│ 2. CAPTURE LESSONS LEARNED (existing, enhanced) │ +│ - Gather lessons from sprint │ +│ - Create wiki page: lessons/sprints/sprint-XX.md │ +│ - ADD: link to implementation page in lesson metadata │ +├─────────────────────────────────────────────────────────────────┤ +│ 3. UPDATE WIKI IMPLEMENTATION PAGE (new) │ +│ - Set Status: Implemented (or Failed) │ +│ - Add link to lessons learned page │ +│ - Add completion date │ +├─────────────────────────────────────────────────────────────────┤ +│ 4. UPDATE WIKI PROPOSAL PAGE (new) │ +│ - Update implementation entry status │ +│ - If ALL implementations complete: │ +│ Set proposal Status: Implemented │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Traceability Chain + +``` +Input (local file / conversation / existing wiki) + │ + ▼ [migrated by /sprint-plan] +Wiki: "Change V04.1.0: Proposal" (persistent) + │ + ▼ [created by /sprint-plan] +Wiki: "Change V04.1.0: Proposal (Implementation 1)" (versioned) + │ + ▼ [referenced in description] +Gitea Issues (#42, #43, #44) + │ + ▼ [referenced in commits] +Git Commits (feat: add wiki workflow, closes #42) + │ + ▼ [captured by /sprint-close] +Wiki: "lessons/sprints/v4.1.0-implementation-1" (linked back) +``` + +## Benefits + +| Benefit | Description | +|---------|-------------| +| **Separation of Concerns** | Planning docs clearly distinct from project documentation | +| **Full Traceability** | Clear path from idea to lessons learned | +| **Iteration Support** | Multiple implementations per proposal | +| **Single Source of Truth** | Wiki is authoritative, local files are temporary | +| **Historical Record** | Easy to review what was planned vs implemented | +| **Cross-Version Learning** | Lessons linked to specific implementations | +| **Flexible Input** | Start from file, conversation, or existing wiki | + +## Implementation Phases + +| Phase | Scope | Effort | +|-------|-------|--------| +| **Phase 1** | Add wiki proposal/implementation creation to `/sprint-plan` | M | +| **Phase 2** | Add wiki status updates to `/sprint-close` | S | +| **Phase 3** | Add cross-linking (issues ↔ wiki, lessons ↔ implementation) | M | +| **Phase 4** | Add `/proposal-status` command for viewing proposal tree | S | + +## MCP Tools Required + +All tools already exist in the Gitea MCP server: +- `list_wiki_pages` - Check existing proposals +- `get_wiki_page` - Read proposal/implementation content +- `create_wiki_page` - Create new proposal/implementation +- `update_wiki_page` - Update status, add links + +## Affected Files + +| File | Changes | +|------|---------| +| `plugins/projman/commands/sprint-plan.md` | Add wiki workflow steps | +| `plugins/projman/commands/sprint-close.md` | Add wiki status updates | +| `plugins/projman/agents/planner.md` | Include wiki workflow in planning | +| `plugins/projman/agents/orchestrator.md` | Include wiki updates in close | +| `plugins/projman/README.md` | Document wiki workflow | + +## Resolved Questions + +| Question | Decision | +|----------|----------| +| **Version vs Sprint numbering** | **Hybrid** - `Change VXX.X.X:` for releases, `Change Sprint-NN:` for internal work | +| **Multi-feature sprints** | **One proposal per feature** - each feature gets its own proposal page | +| **Input document format** | **Standardized frontmatter** - version, title, plugin (optional), type | + +## Success Criteria + +- [ ] Sprint planning creates wiki proposal and implementation pages +- [ ] Sprint close updates wiki statuses +- [ ] Issues reference wiki implementation in description +- [ ] Lessons learned link back to implementation +- [ ] Local input files are deleted after wiki migration +- [ ] `/proposal-status` shows proposal/implementation tree +- [ ] Flexible input: file, conversation, or existing wiki + +--- + +## Implementations + +*No implementations yet.*