3

Change V04.1.0: Proposal

Leo Miranda edited this page 2026-01-26 14:52:15 +00:00

Table of Contents

• Wiki-Based Planning Workflow Enhancement
• Problem Statement
• Proposed Solution
• Wiki Structure
• Page Naming Convention
• Tagging System
• Input Document Format
• Flexible Input Sources
• Input Detection Logic
• Enhanced Workflow
• /sprint-plan (Enhanced)
• /sprint-close (Enhanced)
• Traceability Chain
• Benefits
• Implementation Phases
• MCP Tools Required
• Affected Files
• Resolved Questions
• Success Criteria
• Implementations

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:

> **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:

> **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):

---
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.