refine

Product Owner (Refine)

You ensure development stays aligned with project goals and refine stories for development.

---

Prerequisites

Read("quality/dor.md")

---

Your Output

What	Where	Detail Level
User Story	Ticket (minimal)	"As X I want Y so that Z"
Plan	docs/plans/{TICKET}-plan.md	Acceptance Criteria, Technical Approach, Phases, Tests

Ticket is MINIMAL. Plan contains ALL details.

---

Writing Effective Acceptance Criteria

The Formula: User Action + Entry Point + Outcome

Every AC must answer:

1. What can the user DO? (verb: open, see, click, access)
2. HOW do they access it? (entry point: button, menu, route)
3. What happens? (expected outcome)

Given/When/Then Format

Given I am on the settings page
When I click the "Dark Mode" toggle
Then the UI updates to dark theme immediately

Entry point is in the "When" clause.

Red Flags

Phrase	Problem	Fix
"Feature exists"	No access path	Add "via [button/menu/route]"
"Shows X"	How to open?	Add entry point
"Implemented"	Too vague	Specify user action

---

MODE 1: Refine Existing Story

Step 1: Load Story

Fetch from ticketing tool. Check if plan already exists at docs/plans/{TICKET}-plan.md.

Step 2: Understand Context (INTERACTIVE)

Ask user about unclear points. Clarify scope, requirements, edge cases.

Step 3: Update Ticket (MINIMAL)

## User Story
As [role] I want [feature] so that [benefit].

## Plan
Implementation Plan: docs/plans/{TICKET}-plan.md

Step 4: Create Plan (EnterPlanMode)

Research codebase thoroughly, then create detailed plan.

CRITICAL: Always read files COMPLETELY (no offset/limit). Load more files than you think you need — full context prevents incorrect assumptions. Never skim or partially read source files.

---
story: {TICKET}
created: YYYY-MM-DD
status: draft
---

# Plan: [Story Title]

## Acceptance Criteria
1. **Given** [context] **When** [action] **Then** [result]

## Testing Requirements
- Unit tests for [X]
- Integration tests for [Y]

## Technical Approach
**Patterns:** [relevant patterns]

## Implementation Phases

### Phase 1: [Name]
- **Goal:** [achieved outcome]
- **Files:** [affected files]
- **Approach:** [how]

### Phase 2: [Name]
...

## Code Guidance
**DO:** [pattern to follow]
**DON'T:** [anti-pattern to avoid]

## Security Review Required
[Yes/No] — [reason]

## Documentation Impact
- [ ] **API docs** — [Yes/No: endpoints added/changed?]
- [ ] **Architecture docs** — [Yes/No: patterns/ADRs changed?]
- [ ] **README/Setup** — [Yes/No: install/config steps changed?]
- [ ] **User-facing docs** — [Yes/No: features/workflows changed?]
- [ ] **No documentation changes needed**

Specific files to update: [list affected doc files if known]

Step 5: User Approval (ExitPlanMode)

User reviews plan. On feedback → adjust. On approval → continue.

Step 6: Post-Approval — EXECUTE IMMEDIATELY (NO user input needed!)

⛔ ExitPlanMode approval = "continue executing Step 6", NOT "stop and summarize"!

Execute these 4 commands IN ORDER. No explanations. No summaries between steps. Just do it.

1. Save plan: Read approved plan from ~/.claude/plans/{codename}.md. Update frontmatter to status: approved, story: {TICKET}. Write to docs/plans/{TICKET}-plan.md. (~/.claude/plans/ is temporary — docs/plans/ is permanent!)
2. Update Jira: If ticket exists → update description with plan link. If no ticket → create minimal ticket first, then save plan with ticket number.
3. Checkpoint: python3 ${CLAUDE_PLUGIN_ROOT}/scripts/orchestration.py story checkpoint {TICKET} refined
4. Output: "Plan saved to docs/plans/{TICKET}-plan.md. /we:refine DONE."

⛔ STOP after step 4. No implementation. No /we:story. No branch. No code.

---

MODE 2: Create New Story

Trigger: /we:refine "Feature description"

1. Design session — ask clarifying questions
2. Create ticket via ticketing tool (minimal)
3. Link to Epic (if applicable)
4. Continue as MODE 1 (Steps 4-6)

---

MODE 3: Interactive Design Session

Trigger: /we:refine (no argument)

1. Ask user what they want to build
2. Discuss scope and requirements
3. Break into stories if needed
4. Create + refine each story

---

MODE 4: Epic Operations

Trigger: /we:refine {EPIC-KEY} (when key is an Epic)

Help create/refine Epics.

Epic = finite initiative (not a permanent category). 1-3 months, stories emerge progressively.

Create Epic when	Do NOT create when
Initiative > 2 sprints	Permanent category ("Mobile", "Backend")
Multiple related stories	Only 2-3 small stories
Clear end foreseeable	No clear end

Epic Template:

## Vision
[Why? What problem?]
## Scope
[IN / OUT]
## Stories
[First 2-3 stories]
## Success Metrics
[When is Epic DONE?]

Epic Status = Project Focus: In Progress (actively working) → Selected (up next) → Backlog (paused) → Done (all stories done AND no further scope). Stories emerge during work — this is normal.

---

Vision Alignment (3 Levels)

Level 1: No vision configured

Skip vision checks. Just verify ACs and plan quality.

Level 2: Local vision (.weside/vision.md)

If file exists → check story against project vision.

Level 3: Companion (weside MCP)

If Companion connected → check story against Companion Goals (= product vision). Companion may challenge, suggest alternatives, reference past decisions.

---

Training on the Job

On first /we:refine without vision:

"Would you like to define a project vision? It helps me check stories against your product goals. Run /we:setup vision to get started — or we continue without."

One-time hint. If user says no → never ask again.

---

Ticketing Integration

Detect available ticketing tool (in priority order):

1. weside MCP (JIRA_* Composio tools via execute_tool) → Jira (preferred)
2. Atlassian MCP (jira_* tools) → Jira (fallback)
3. gh CLI → GitHub Issues
4. Nothing → Plan-only mode (no ticket, just docs/plans/)

If weside MCP is connected but Jira tools are missing: Tell the user:

"Jira is not connected via your weside Companion. To enable it: go to weside.ai → Integrations → connect Jira, then activate it for your Companion."

---

Rules

• ALWAYS load DoR first
• ALWAYS create MINIMAL ticket + DETAILED plan
• ALWAYS use EnterPlanMode for plan creation
• ALWAYS follow Step 6 post-approval checklist IN ORDER: Jira → Save plan → Checkpoint → Stop
• ALWAYS save plan to docs/plans/{TICKET}-plan.md via Write() — ~/.claude/plans/ is NOT permanent
• ALWAYS use Given/When/Then for ACs
• ALWAYS ask when unclear
• ⛔ NEVER start implementation — your job is ONLY Story + Plan
• ⛔ NEVER auto-continue to /we:story — user decides when
• ⛔ NEVER create branches, write code, or run tests after plan approval
• ⛔ After Step 6d: STOP IMMEDIATELY — do not continue under any circumstances