From 0b538aebbdb7c77086068654c02c368e3445de67 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Mon, 26 Jan 2026 14:24:28 +0000 Subject: [PATCH] Update Change V04.1.0: Proposal --- ...oposal.md => Change-V04.1.0%3A-Proposal.md | 395 +++++++++--------- 1 file changed, 198 insertions(+), 197 deletions(-) rename Change-V03.2.0%3A-Proposal.md => Change-V04.1.0%3A-Proposal.md (94%) diff --git a/Change-V03.2.0%3A-Proposal.md b/Change-V04.1.0%3A-Proposal.md similarity index 94% rename from Change-V03.2.0%3A-Proposal.md rename to Change-V04.1.0%3A-Proposal.md index d3e7299..1297ff3 100644 --- a/Change-V03.2.0%3A-Proposal.md +++ b/Change-V04.1.0%3A-Proposal.md @@ -1,197 +1,198 @@ -> **Type:** Change Proposal -> **Version:** V03.2.0 -> **Plugin:** projman -> **Status:** Pending -> **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 - ├── v03.2.0/ - │ ├── proposal.md - │ └── implementation-1.md - └── v04.0.0/ - ├── proposal.md - └── implementation-1.md -``` - -### Page Naming Convention - -| Type | Pattern | Example | -|------|---------|---------| -| Proposal | `Change VXX.X.X: Proposal` | Change V03.2.0: Proposal | -| Implementation | `Change VXX.X.X: Proposal (Implementation N)` | Change V03.2.0: Proposal (Implementation 1) | - -### 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) -``` - -## Enhanced Workflow - -### /sprint-plan (Enhanced) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ PREPARATION PHASE │ -│ User creates: docs/changes/v3.2.0-feature-description.md │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ /sprint-plan Execution │ -│ │ -│ 1. Validate branch, repo, labels (existing) │ -│ 2. Read input document from docs/changes/ │ -│ 3. Search lessons learned (existing) │ -│ 4. Create/Update wiki: "Change VXX.X.X: Proposal" │ -│ - If new version: create proposal page │ -│ - If exists: add new implementation link │ -│ 5. Create wiki: "Change VXX.X.X: Proposal (Implementation N)" │ -│ - Tags: Type, Version, Status=In Progress, Date, Origin │ -│ - Content: migrated from input document │ -│ 6. Architecture analysis + clarifying questions (existing) │ -│ 7. Create Gitea Issues with wiki implementation reference │ -│ 8. Delete local input file (single source of truth in wiki) │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### /sprint-close (Enhanced) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ /sprint-close Execution │ -│ │ -│ 1. Verify all issues closed (existing) │ -│ 2. Capture lessons learned (existing) │ -│ 3. Update wiki implementation page: │ -│ - Status: Implemented │ -│ - Link to lessons learned │ -│ 4. Update wiki proposal page: │ -│ - Update implementation status │ -│ - Update overall status if all implementations complete │ -└─────────────────────────────────────────────────────────────────┘ -``` - -## Traceability Chain - -``` -Input Document (local, temporary) - ↓ [migrated by sprint-plan] -Wiki Proposal (persistent) - ↓ [created by sprint-plan] -Wiki Implementation (versioned) - ↓ [created by sprint-plan] -Gitea Issues (with wiki reference) - ↓ [execution] -Git Commits (with issue reference) - ↓ [captured by sprint-close] -Lessons Learned (linked to implementation) -``` - -## 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 | - -## 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 | - -## Open Questions - -1. **Version vs Sprint numbering** - What if a sprint doesn't have a version change? - - Option A: Use sprint number (Change Sprint-17: Proposal) - - Option B: Always require version (even patch versions) - -2. **Multi-feature sprints** - How to handle sprints with multiple unrelated features? - - Option A: One proposal per feature - - Option B: Group under sprint proposal - -3. **Input document format** - Should we standardize the input document structure? - - Suggested: Frontmatter with version, title, description - -## 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 - ---- - -## Implementations - -*No implementations yet.* +> **Type:** Change Proposal +> **Version:** V04.1.0 +> **Plugin:** projman +> **Status:** Pending +> **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) | + +### 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) +``` + +## Enhanced Workflow + +### /sprint-plan (Enhanced) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PREPARATION PHASE │ +│ User creates: docs/changes/v4.1.0-feature-description.md │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ /sprint-plan Execution │ +│ │ +│ 1. Validate branch, repo, labels (existing) │ +│ 2. Read input document from docs/changes/ │ +│ 3. Search lessons learned (existing) │ +│ 4. Create/Update wiki: "Change VXX.X.X: Proposal" │ +│ - If new version: create proposal page │ +│ - If exists: add new implementation link │ +│ 5. Create wiki: "Change VXX.X.X: Proposal (Implementation N)" │ +│ - Tags: Type, Version, Status=In Progress, Date, Origin │ +│ - Content: migrated from input document │ +│ 6. Architecture analysis + clarifying questions (existing) │ +│ 7. Create Gitea Issues with wiki implementation reference │ +│ 8. Delete local input file (single source of truth in wiki) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### /sprint-close (Enhanced) + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ /sprint-close Execution │ +│ │ +│ 1. Verify all issues closed (existing) │ +│ 2. Capture lessons learned (existing) │ +│ 3. Update wiki implementation page: │ +│ - Status: Implemented │ +│ - Link to lessons learned │ +│ 4. Update wiki proposal page: │ +│ - Update implementation status │ +│ - Update overall status if all implementations complete │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Traceability Chain + +``` +Input Document (local, temporary) + ↓ [migrated by sprint-plan] +Wiki Proposal (persistent) + ↓ [created by sprint-plan] +Wiki Implementation (versioned) + ↓ [created by sprint-plan] +Gitea Issues (with wiki reference) + ↓ [execution] +Git Commits (with issue reference) + ↓ [captured by sprint-close] +Lessons Learned (linked to implementation) +``` + +## 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 | + +## 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 | + +## Open Questions + +1. **Version vs Sprint numbering** - What if a sprint doesn't have a version change? + - Option A: Use sprint number (Change Sprint-17: Proposal) + - Option B: Always require version (even patch versions) + +2. **Multi-feature sprints** - How to handle sprints with multiple unrelated features? + - Option A: One proposal per feature + - Option B: Group under sprint proposal + +3. **Input document format** - Should we standardize the input document structure? + - Suggested: Frontmatter with version, title, description + +## 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 + +--- + +## Implementations + +*No implementations yet.*