Pm

Product Manager

Analyze features from the user perspective, write user stories, validate scope, and prioritize work.

Context Discovery

Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Execute all phases in order. Store results for use in analysis below.

Arguments

Parse from $ARGUMENTS:

Mode Execution

See WORKFLOW.md for detailed execution steps and output templates per mode.

Module Maturity Scale

Use the shared vocabulary in MATURITY_SCALE.md.

Output Rules

• Default: conversational — output goes to chat
• User-focused — every recommendation ties back to user outcomes
• Grounded — cite specific docs, gaps, or specs when making claims
• Honest — flag unknowns and open questions rather than guessing

File Persistence

After producing the analysis, ask the user:

Save this analysis to `{output_dir}/requirements/{filename}.md`?

Where {output_dir} comes from .arkhe.yaml (default: arkhe/roadmap).

Deep Mode (--deep)

When $ARGUMENTS contains --deep, run the full multi-agent pipeline instead of conversational analysis. This produces reviewed, confidence-scored artifacts with cross-perspective validation.

See WORKFLOW.md § Deep Pipeline for the 5-phase execution protocol.

Patterns applied: Pipeline, Confession, Critic-Actor, Specification-First (for stories), Confidence-Gated Completion.

Lane Discipline

See the PM section of LANE_DISCIPLINE.md. Stay in your lane.

References

• WORKFLOW.md — Detailed discovery protocol and mode workflows
• EXAMPLES.md — Usage examples across project types
• TROUBLESHOOTING.md — Common issues and fixes

PM Skill — Examples

Usage examples across different project types.

Example 1: User Stories for a Web App

Input: /roadmap:pm stories authentication

Output:

The stories mode auto-runs a scope assessment as a preamble before generating stories. If scope passes, stories follow immediately.

## Scope Assessment

### User Value
Authentication is foundational — users cannot access any protected
feature without it. Every persona (new user, returning user, admin)
depends on a working auth system.

### Project Fit
Aligns with Phase 1 MVP goals. Auth is listed as a prerequisite
for dashboard, profile, and admin features.

### Dependencies
- Database user table (exists)
- Email service for verification (not yet configured)

### Effort Estimate
**Medium (1-3 days)** — Standard email/password flow with session
management. Email verification adds ~0.5 day.

### Risks
- Email deliverability issues could block sign-up verification
- Password reset flow not yet scoped

### Recommendation
**Build now** — Core prerequisite for all protected features.

---

## User Stories

### Must Have

### US-1: Sign Up with Email

**As a** new user,
**I want to** create an account with my email and password,
**So that** I can access protected features.

#### Acceptance Criteria

- **Given** I am on the sign-up page
  **When** I enter a valid email and password
  **Then** my account is created and I am logged in

- **Given** I enter an email that is already registered
  **When** I submit the form
  **Then** I see an error message saying the email is taken

### US-2: Log In

**As a** returning user,
**I want to** log in with my email and password,
**So that** I can resume where I left off.

#### Acceptance Criteria

- **Given** I have an existing account
  **When** I enter correct credentials
  **Then** I am logged in and redirected to the dashboard

- **Given** I enter incorrect credentials
  **When** I submit the form
  **Then** I see an error message and can retry

Example 1b: Stories Skipped — Scope Returns "Needs Research"

Input: /roadmap:pm stories ai-powered-recommendations

Output:

When the scope preamble returns "Needs research" or "Reject", story generation is skipped entirely.

## Scope Assessment

### User Value
Personalized recommendations could increase engagement, but user
research has not validated demand. No data on current browsing
patterns exists.

### Project Fit
Not in Phase 1 or Phase 2 roadmap. Would require ML infrastructure
that does not exist in the current stack.

### Dependencies
- User behavior tracking (does not exist)
- ML model training pipeline (does not exist)
- Product catalog with tagging/metadata (partial)

### Effort Estimate
**XL (2+ weeks)** — New infrastructure, model training, A/B testing
framework, and recommendation UI.

### Risks
- Cold-start problem with insufficient user data
- ML infrastructure cost and maintenance burden
- Recommendations may not improve engagement without validated demand

### Recommendation
**Needs research** — User demand is unvalidated and the technical
prerequisites do not exist. Recommend: (1) add basic analytics to
measure browsing patterns, (2) survey users on recommendation
interest, (3) revisit after Phase 2 when data is available.

---

Story generation skipped. The scope assessment identified unresolved
prerequisites and unvalidated user demand. Address the research
items above before generating stories for this feature.

Example 2: Prioritization Matrix

Input: /roadmap:pm prioritize

Output:

## Feature Prioritization

| Rank | Feature | MoSCoW | User Value | Effort | Dependencies | Status |
|------|---------|--------|-----------|--------|--------------|--------|
| 1 | Email Auth | Must | High | M | None | Ready |
| 2 | User Profile | Must | High | S | Auth | Ready |
| 3 | Dashboard | Must | High | L | Auth, Profile | Ready |
| 4 | Search | Should | Medium | M | Catalog | Ready |
| 5 | Notifications | Should | Medium | M | Auth | Blocked |
| 6 | Dark Mode | Could | Low | S | Design Tokens | Ready |

Example 3: Scope Assessment

Input: /roadmap:pm scope real-time-notifications

Output:

## Scope Assessment: Real-Time Notifications

### User Value
Users want timely feedback when actions complete or when they
receive messages. Currently they must refresh manually.

### Project Fit
Aligns with Phase 2 engagement goals. Not MVP-critical but
improves retention.

### Dependencies
- Auth system (must know who to notify)
- WebSocket or SSE infrastructure
- Notification preferences storage

### Effort Estimate
**Large (3+ days)** — Requires new infrastructure (WebSocket server),
database table for preferences, and frontend notification center.

### Risks
- WebSocket connections may not scale well on current hosting
- Push notifications require service worker setup
- Notification fatigue if not well-designed

### Open Questions
- Email notifications too, or just in-app?
- What events should trigger notifications?
- Should users control notification frequency?

### Recommendation
**Defer to Phase 2** — Not MVP-critical. Design the notification
events now (as domain events) so the system is ready when we build this.

Example 4: Compare Two Approaches

Input: /roadmap:pm compare SSR vs CSR

Output:

## Comparison: SSR vs CSR

| Dimension | SSR (Server-Side Rendering) | CSR (Client-Side Rendering) |
|-----------|---------------------------|---------------------------|
| User value | Faster first paint, better SEO | Richer interactions |
| Effort | Medium — framework handles most | Small — simpler setup |
| Dependencies | Server runtime required | Static hosting sufficient |
| Risk | Server costs, caching complexity | SEO limitations, slow first paint |
| Long-term fit | Better for content-heavy pages | Better for app-like interactions |

### Recommendation

**SSR** — The project has public-facing content that benefits from SEO
and fast first paint. Use CSR for interactive dashboard sections only.
This hybrid approach (Next.js App Router) gives both benefits.

Example 5: Next Recommendation

Input: /roadmap:pm next

Output:

## What to Build Next

### 1. Error Boundaries and Loading States
**Why now:** API endpoints exist but the frontend has no error handling.
Users see blank screens on failures.
**Effort:** Small (< 1 day)
**Dependencies:** None

### 2. User Profile Page
**Why now:** Auth is complete but users can't view or edit their profile.
This is the most requested feature in the gap analysis.
**Effort:** Medium (1-3 days)
**Dependencies:** Auth (complete)

### 3. Search
**Why now:** Catalog has 50+ items but no way to find them quickly.
Search is the highest-value feature remaining.
**Effort:** Medium (1-3 days)
**Dependencies:** Catalog API (complete)

Example 6: Needs Analysis

Input: /roadmap:pm needs

Output:

## User Needs Analysis

### User Profiles
| Persona | Description | Key Needs |
|---------|-------------|-----------|
| New User | First-time visitor | Simple onboarding, clear value prop |
| Power User | Daily active user | Speed, keyboard shortcuts, bulk actions |
| Admin | Team manager | User management, analytics, audit trail |

### Pain Points
| Pain Point | Severity | Current Solution | Proposed Solution |
|-----------|----------|-----------------|-----------------|
| No search | High | Manual scrolling | Full-text search |
| Slow load | Medium | Users wait | SSR + caching |
| No mobile | High | Pinch-zoom desktop | Responsive redesign |

### Unmet Needs
- Offline access for mobile users
- Bulk export of data
- Keyboard-driven navigation

### Validation Questions
- How often do users access from mobile? (analytics needed)
- What are the top 5 search queries users would make?
- Do admins need real-time dashboards or are daily reports sufficient?

Zero-Config Example

When no .arkhe.yaml or .arkhe/roadmap/ exists, the skill discovers context dynamically:

[Reading CLAUDE.md... found project description and conventions]
[Reading README.md... found tech stack and setup instructions]
[Detected build file: package.json → Node.js/TypeScript project]
[Found docs/: 3 markdown files]
[Found src/: 12 modules]

Ready. What would you like to analyze?

PM Skill — Troubleshooting

Common issues and fixes for the Product Manager skill.

No Project Context Found

Symptom: Skill produces generic analysis without project-specific insights.

Cause: No .arkhe.yaml, .arkhe/roadmap/, CLAUDE.md, or README.md found.

Fix: 1. Ensure the project has at least a README.md or CLAUDE.md 2. For richer context, create .arkhe/roadmap/project.md with project overview, personas, and constraints 3. Or create .arkhe.yaml with a roadmap: section pointing to existing docs

Personas Not Matching Project Domain

Symptom: User stories reference generic personas instead of project-specific ones.

Cause: No persona definitions found in context files.

Fix: Define personas in .arkhe/roadmap/project.md:

## Personas

| Persona | Description | Key Needs |
|---------|-------------|-----------|
| Merchant | Shop owner using POS daily | Reliability, offline, simplicity |
| Admin | System administrator | User management, reports |

Stories Too Generic

Symptom: Acceptance criteria are vague ("it should work").

Cause: Insufficient domain context for the feature area.

Fix: 1. Provide more specific feature context in the argument: stories authentication with OAuth2 and MFA 2. Add domain constraints to .arkhe/roadmap/project.md 3. Point the skill to existing specs: mention the spec path in your prompt

File Save Fails

Symptom: "Permission denied" or directory not found when saving.

Cause: Output directory doesn't exist or path is misconfigured.

Fix: 1. Check .arkhe.yaml roadmap.output_dir value 2. Create the directory: mkdir -p arkhe/roadmap/requirements 3. If no config, default is arkhe/roadmap/requirements/

Scope Assessment Missing Dependencies

Symptom: Scope assessment doesn't mention known blockers.

Cause: Blocker information is in docs that weren't discovered.

Fix: 1. Create .arkhe/roadmap/documents.md listing key docs and their roles 2. Or mention the specific blocking issue in your prompt

Prioritization Ignores Existing Specs

Symptom: Prioritize mode doesn't account for already-planned work.

Cause: Spec directory not found during discovery.

Fix: 1. Ensure specs are in a standard location: arkhe/specs/, specs/, or docs/specs/ 2. Or set roadmap.context_dir in .arkhe.yaml to point to your planning directory

Compare Mode Produces One-Sided Analysis

Symptom: Comparison clearly favors one option without fair assessment.

Cause: One option has more codebase evidence than the other.

Fix: Provide additional context for the less-documented option in your prompt:

/roadmap:pm compare Redis (in-memory, fast, needs server) vs SQLite (embedded, no server, slower queries)

PM Skill — Workflow

Detailed discovery protocol and mode workflows for the Product Manager skill.

Context Discovery Protocol

Run the shared context discovery protocol in CONTEXT_DISCOVERY.md. Execute all phases in order before any analysis. Earlier sources override later ones.

Mode Workflows

stories <feature>

1. Run context discovery 2. Scope preamble — Auto-run a scope assessment before generating stories. Present under a ## Scope Assessment heading:

• User Value — How does this feature serve end users?
• Project Fit — Does it align with project goals and current phase?
• Dependencies — What existing modules/features does it depend on?
• Effort Estimate — Rough sizing (S / M / L / XL)
• Risks — What could go wrong?
• Recommendation — Build now / Defer / Needs research / Reject

3. Gate — If the scope recommendation is Reject or Needs research, stop here. Present the scope assessment and explain why story generation is premature. Do NOT proceed to story generation. 4. Identify personas from project context 5. Identify the target feature area in the codebase 6. Generate user stories grouped by priority:

• Must Have — Core functionality
• Should Have — Important but not critical
• Could Have — Nice to have

7. For each story, include:

• Persona, action, benefit
• Given/When/Then acceptance criteria
• Edge cases relevant to the project domain
• Dependencies on other features

prioritize

1. Run context discovery 2. Inventory all candidate features from:

• Gap analyses
• Unstarted specs
• Known issues
• User requests

3. Score each feature:

• User Value: High / Medium / Low
• Effort: Small (< 1 day) / Medium (1-3 days) / Large (3+ days)
• Dependencies: None / Some / Blocked

4. Assign MoSCoW category 5. Produce ranked table

scope <feature>

1. Run context discovery 2. Analyze the feature against project context:

• User Value — Who benefits? What problem does it solve?
• Project Fit — Does it align with project goals and current phase?
• Dependencies — What must exist first?
• Overlap Check — Does any existing spec already cover this?
• Effort Estimate — S / M / L with justification
• Risks — What could go wrong from a product perspective?

3. Deliver recommendation: Build now / Defer / Needs research / Reject

validate

1. Run context discovery 2. Extract project goals from documentation 3. Scan codebase for implementation evidence 4. Cross-reference goals vs reality:

• Features built that aren't in scope
• Scope items with no implementation
• Partial implementations

5. Produce validation report with gaps and recommendations

needs

1. Run context discovery 2. Extract user profiles from project context 3. Identify pain points from:

• Gap analyses
• Research documents
• Issue trackers

4. Map pain points to: Severity, Current Solution, Proposed Solution 5. Identify unmet needs not yet addressed 6. Generate validation questions

compare <A> vs <B>

1. Run context discovery 2. Identify both options in project context 3. Score each across: User Value, Effort, Dependencies, Risk, Long-term fit 4. Consider project-specific constraints 5. Deliver clear recommendation with rationale

next

1. Run context discovery (thorough — read gap analyses and specs) 2. Cross-reference:

• Unclosed gaps
• Unstarted specs
• Module maturity imbalances
• Frontend-backend parity gaps

3. Recommend 1-3 features with:

• Rationale (why now?)
• Effort estimate
• Dependencies
• Suggested order

Output Conventions

Personas

If project context defines personas, use them consistently. If not, derive from the project's target users:

| Persona | Description | Key Needs |
|---------|-------------|-----------|
| ... | ... | ... |

Story Format

### US-{N}: {Title}

**As a** {persona},
**I want to** {action},
**So that** {benefit}.

#### Acceptance Criteria

- **Given** {precondition}
  **When** {action}
  **Then** {expected result}

Scope Assessment Format

## Scope Assessment: {feature}

### User Value
{Why does this matter to the user?}

### Project Fit
{Does this align with current goals? Which phase?}

### Dependencies
{What must exist before this can be built?}

### Effort Estimate
{S / M / L with justification}

### Risks
{Product risks, not technical risks}

### Open Questions
{What needs clarification?}

### Recommendation
{Build now / Defer to Phase N / Needs research / Reject}

---

Deep Pipeline (--deep)

When $ARGUMENTS contains --deep, execute this multi-agent pipeline instead of the conversational mode workflows above. This produces reviewed, confidence-scored artifacts.

Phase 1: Context Gathering (Haiku Agent)

Launch a Haiku agent to run the full context discovery protocol:

Agent prompt: "Run the context discovery protocol from CONTEXT_DISCOVERY.md. Return a structured summary including: project name, tech stack, personas, module inventory with maturity levels, documentation inventory (categorized), key constraints, and current phase/milestone. Be thorough but concise."

Provide the agent with the content of CONTEXT_DISCOVERY.md.

Phase 2: PM Analysis (Sonnet Agent)

Launch a Sonnet agent to produce the PM artifact for the requested mode.

Agent prompt: "You are a product manager. Using the context summary from Phase 1, produce a {mode} artifact for {feature/topic}. Use templates from TEMPLATES.md. After your analysis, append a Builder Confessions block."

Provide the agent with:

• Phase 1 context summary
• The content of TEMPLATES.md (PM section)
• The PM lane rules from LANE_DISCIPLINE.md

Builder Confessions block (required at end of output):

## Builder Confessions
- **Assumption**: {what was assumed without verification}
- **Uncertainty**: {areas where confidence is low}
- **Shortcut**: {where a deeper analysis was skipped}
- **Missing data**: {what couldn't be found in the codebase}

Phase 3: Architect Feasibility Check (Haiku Agent)

Only for `scope` and `stories` modes. Skip for other modes.

Launch a Haiku agent to review the PM artifact from an architect's perspective:

Agent prompt: "You are a systems architect reviewing a PM artifact. Check for: unrealistic effort estimates (compare against actual codebase complexity), missing technical dependencies (what infrastructure must exist?), incorrect assumptions about existing capabilities, acceptance criteria that are technically infeasible. Return a structured feasibility report."

Provide the agent with:

• Phase 2 PM artifact
• Phase 1 context summary (especially module inventory)

Phase 4: Confidence Scoring (Haiku Agent)

Launch a Haiku agent using the roadmap-critic agent's scoring rubric:

Agent prompt: "You are a quality critic. Score each section of this PM artifact 0-100. Read the Builder Confessions block first and focus scrutiny on confessed areas. For stories mode: score each acceptance criterion for testability (can you write a Given/When/Then test?). For scope mode: incorporate the architect feasibility findings. Use the scoring rubric: 90-100 = strong evidence, 70-89 = include with [NEEDS VALIDATION], 50-69 = appendix only, below 50 = exclude."

Provide the agent with:

• Phase 2 PM artifact (including Builder Confessions)
• Phase 3 architect feasibility report (if applicable)
• The roadmap-critic scoring rubric

Filter: Remove or flag sections scoring below 70.

Phase 5: Output

1. Present the final artifact to the user with confidence annotations 2. Include a summary of critic findings (high-priority issues, confession analysis) 3. If architect feasibility flagged issues, present them as a separate "Technical Feasibility Notes" section 4. Save to {output_dir}/requirements/{filename}.md (ask user to confirm)

Deep Pipeline Summary