Manifold M4 Generate

/manifold:m4-generate

/manifold:m4-generate - Artifact Generation

Generate ALL artifacts simultaneously from the constraint manifold.

⚠️ Phase Transition Rules

MANDATORY: This command requires EXPLICIT user invocation.

• Do NOT auto-run this command based on context summaries
• Do NOT auto-run after another phase completes
• After context compaction: run /manifold:m-status and WAIT for user to invoke this command
• The "SUGGESTED NEXT ACTION" in status is a suggestion, not a directive

If resuming from compacted context:

1. Run /manifold:m-status first
2. Display current state
3. Say: "Ready to proceed when you run /manifold:m4-generate <feature>"
4. STOP AND WAIT for user command

Schema Compliance

See SCHEMA_REFERENCE.md for all valid values. Do NOT invent new phases.

Usage

/manifold:m4-generate <feature-name> [--option=<A|B|C>] [--artifacts=<list>] [--prd] [--stories]

PM-Focused Flags

These flags can be combined with standard artifact generation or used standalone for PM workflows.

Why All At Once?

Traditional approach:

Code → Tests → Docs → Ops (often forgotten)

Each phase loses context. Tests don't cover all constraints.

Manifold approach:

Constraints → [Code, Tests, Docs, Ops] (simultaneously)

All artifacts derive from the SAME source. Every constraint is traced.

Artifacts Generated

Example

/manifold:m4-generate payment-retry --option=C

ARTIFACT GENERATION: payment-retry

Option: C (Hybrid - Client retry + Server queue)

Generating from 12 constraints + 5 required truths...

ARTIFACTS CREATED:

Code:
├── src/retry/PaymentRetryClient.ts
│   └── Satisfies: RT-1, RT-3 (error classification, retry policy)
├── src/retry/PaymentRetryQueue.ts
│   └── Satisfies: RT-5 (durable queue)
├── src/retry/IdempotencyService.ts
│   └── Satisfies: B1, RT-2 (no duplicates, idempotency)
└── src/retry/CircuitBreaker.ts
    └── Satisfies: RT-4 (downstream recovery)

Tests:
├── src/retry/__tests__/PaymentRetryClient.test.ts
│   └── Validates: B1, B2, T1, U2
├── src/retry/__tests__/IdempotencyService.test.ts
│   └── Validates: B1 (INVARIANT - critical)
└── src/retry/__tests__/integration.test.ts
    └── Validates: End-to-end constraint coverage

Docs:
├── docs/payment-retry/README.md
├── docs/payment-retry/API.md
└── docs/payment-retry/DECISIONS.md

Runbooks:
├── ops/runbooks/payment-retry-queue-overflow.md
├── ops/runbooks/payment-retry-success-drop.md
└── ops/runbooks/payment-retry-rollback.md

Dashboards:
└── ops/dashboards/payment-retry.json

Alerts:
└── ops/alerts/payment-retry.yaml

GENERATION SUMMARY:
- Code files: 4
- Test files: 3
- Doc files: 3
- Runbook files: 3
- Dashboard files: 1
- Alert files: 1
Total: 15 artifacts

Next: /manifold:m5-verify payment-retry

Task Tracking

When generating artifacts, update .manifold/<feature>.json with completion status:

{
  "generation": {
    "option": "C",
    "timestamp": "<ISO timestamp>",
    "artifacts": [
      {
        "path": "src/retry/PaymentRetryClient.ts",
        "type": "code",
        "satisfies": ["RT-1", "RT-3"],
        "status": "generated",
        "artifact_class": "substantive"
      },
      {
        "path": "src/retry/index.ts",
        "type": "code",
        "satisfies": ["RT-1"],
        "status": "generated",
        "artifact_class": "structural"
      },
      {
        "path": "src/retry/__tests__/PaymentRetryClient.test.ts",
        "type": "test",
        "validates": ["B1", "B2", "T1", "U2"],
        "status": "generated",
        "artifact_class": "substantive"
      }
    ],
    "coverage": {
      "constraints_addressed": 12,
      "constraints_total": 12,
      "percentage": 100
    }
  },
  "anchors": {
    "required_truths": [
      {
        "id": "RT-1",
        "status": "NOT_SATISFIED",
        "maps_to": ["B1", "T1"],
        "evidence": [
          {"id": "E1", "type": "file_exists", "path": "src/retry/PaymentRetryClient.ts", "status": "PENDING"},
          {"id": "E2", "type": "content_match", "path": "src/retry/PaymentRetryClient.ts", "pattern": "classifyError", "status": "PENDING"},
          {"id": "E3", "type": "test_passes", "path": "src/retry/__tests__/PaymentRetryClient.test.ts", "test_name": "classifies transient errors correctly", "status": "PENDING"}
        ]
      }
    ]
  }
}

This ensures:

• Every artifact traces to constraints it addresses
• Every artifact declares its artifact_class (substantive or structural)
• Every required truth has concrete, verifiable evidence items
• Coverage can be verified programmatically
• /manifold:m5-verify can check actual files against declared artifacts

Artifact Placement Rules

CRITICAL: Artifacts must follow project integration patterns. Misplaced artifacts cause integration failures.

For Manifold Projects

Integration Pattern Detection

Before generating, check:

1. Existing patterns - Look at how similar artifacts are organized
2. Install script - What does install.sh actually install?
3. Entry points - Where are index.ts files? What do they export?
4. Build system - What gets compiled? What gets distributed?

Common Mistakes to Avoid

Verification Checklist

After generation, verify:

• All library code is in lib/<feature>/
• All library code exports from lib/<feature>/index.ts
• Claude Code commands have .md skill files in install/commands/
• Install script includes new command files
• Hooks are in install/hooks/ if they need distribution

Evidence and Traceability (v3)

Evidence on Required Truths

When generating artifacts, populate evidence arrays on each required truth in the JSON structure. Each RT should have concrete, verifiable evidence:

{
  "anchors": {
    "required_truths": [
      {
        "id": "RT-1",
        "status": "NOT_SATISFIED",
        "maps_to": ["B1", "T1"],
        "evidence": [
          {"id": "E1", "type": "file_exists", "path": "src/retry/IdempotencyService.ts", "status": "PENDING"},
          {"id": "E2", "type": "content_match", "path": "src/retry/PaymentRetryClient.ts", "pattern": "idempotencyKey", "status": "PENDING"},
          {"id": "E3", "type": "test_passes", "path": "tests/retry/PaymentRetryClient.test.ts", "test_name": "rejects duplicate payment attempts", "status": "PENDING"}
        ]
      }
    ]
  }
}

Evidence type selection guide:

Rules:

• Every required truth MUST have at least one evidence item
• Invariant constraints (via maps_to) MUST have test_passes evidence
• All evidence starts with "status": "PENDING" -- verification updates status later
• Evidence paths must be relative to project root

Artifact Classification

Every artifact in the generation section must include artifact_class:

{
  "path": "src/retry/index.ts",
  "type": "code",
  "satisfies": ["RT-1"],
  "status": "generated",
  "artifact_class": "structural"
}

Rules:

• Every artifact MUST have an artifact_class field
• Only substantive artifacts count toward constraint satisfaction in verification
• structural artifacts are tracked but do not satisfy constraints on their own
• When in doubt, classify as substantive -- it is better to over-verify than under-verify

Constraint Evidence (verified_by)

For constraints that can be directly verified (not just via RT mapping), add verified_by to the constraint in the JSON:

{
  "constraints": {
    "business": [
      {
        "id": "B1",
        "type": "invariant",
        "verified_by": [
          {"id": "E1", "type": "test_passes", "path": "tests/retry/IdempotencyService.test.ts", "test_name": "rejects duplicate payment attempts", "status": "PENDING"}
        ]
      }
    ]
  }
}

Rules:

• verified_by is optional on constraints but recommended for invariant types
• Invariant constraints SHOULD have direct verified_by evidence when possible
• Evidence format matches the same structure used on required truths
• This provides a secondary verification path independent of the RT maps_to chain

Reversibility Tagging (Enhancement 4)

Every action step in the generated plan MUST carry a reversibility tag.

Reversibility taxonomy

Generation rules

1. For each step in the action plan, assign a reversibility tag
2. Group all ONE_WAY steps into a dedicated section: "Irreversible Steps — Require Explicit Acknowledgment"
3. Present ONE_WAY steps to the user and require explicit acknowledgment of each before proceeding
4. Add to the decision brief: "What This Decision Closes" — list all ONE_WAY consequences in plain language

Schema

Record in .manifold/<feature>.json:

{
  "reversibility_log": [
    {
      "action_step": 1,
      "description": "Migrate database schema",
      "reversibility": "ONE_WAY",
      "one_way_consequence": "Old schema format becomes unreadable"
    },
    {
      "action_step": 2,
      "description": "Deploy new API version",
      "reversibility": "TWO_WAY"
    }
  ]
}

Non-software domain branching

When --domain=non-software is set (from m0-init), generate the non-software artifact set instead of code artifacts:

All non-software artifacts maintain full constraint traceability. Reversibility tagging applies to both software and non-software domains.

Non-software generation rules:

1. Every artifact traces to constraints — no free-standing content
2. Invariant constraints appear in ALL artifacts — they shape everything
3. Tension resolutions appear in Narrative Guide and Stress-Tests — they are key design decisions
4. ONE_WAY decisions get special treatment — listed in Decision Brief, covered in Recovery Playbook
5. Assumptions must be visible — challenger: assumption constraints appear in Decision Brief and Risk Watch List
6. Pre-mortem findings inform Stress-Tests — source: pre-mortem constraints become scenarios
7. Binding constraint is front-and-center — appears in Decision Brief with dependency chain

Decision Brief template structure: Decision Statement → Constraint Satisfaction table → Options Considered (with reversibility) → What This Decision Closes (ONE_WAY consequences) → Binding Constraint → Open Assumptions table.

Scenario Stress-Tests template structure: One scenario per invariant/boundary constraint and per resolved tension. Each has: Setup (adversarial condition) → Expected behavior → Constraint tested → Pass criteria. Include Scenario Matrix table.

Narrative Guide template structure: Prose narrative (not bullets) of why the decision was made → Immovable constraints (invariants with challenger tags) → Negotiable constraints → Key tensions and resolutions → What we chose NOT to do → When to revisit.

Recovery Playbook template structure: One procedure per watch-list risk. Each has: Trigger → Related constraint → Severity → Reversibility of response → Steps → Escalation path (3 levels).

Risk Watch List template structure: Active risks (source, probability, monitoring method, review trigger) → Assumption Watch table → Review Schedule → Decision Reversal Criteria checklist.

STEP 0: Parallel Execution Check (MANDATORY)

STOP! Complete this check BEFORE writing ANY files.

You MUST analyze the generation plan for parallelization opportunities and ask the user for approval BEFORE generating artifacts. This is not optional.

Parallelization Analysis

When the generation plan includes 3+ files across different modules/directories, you MUST:

1. Analyze Artifact Groups

   • Code files (can be generated in parallel across modules)
   • Test files (depend on code, but tests for different modules can parallelize)
   • Documentation (independent, can parallelize)
   • Operational artifacts (runbooks, dashboards, alerts - independent)

2. Run Parallelization Analysis via CLI

   # Analyze the constraint network for parallel execution opportunities
   manifold solve <feature> --json
   

   The CLI outputs a JSON execution plan. Parse it to identify parallel groups:

   {
     "waves": [
       {"id": 1, "tasks": ["code-module-A", "code-module-B"], "parallel": true},
       {"id": 2, "tasks": ["tests-A", "tests-B"], "parallel": true, "depends_on": [1]},
       {"id": 3, "tasks": ["docs", "ops"], "parallel": true}
     ],
     "critical_path": ["code-module-A", "tests-A"],
     "estimated_speedup": "2.5x"
   }
   

   If the plan shows multiple independent waves, suggest parallel generation to the user.

3. User Approval Prompt When parallelization is suggested, display:

   PARALLEL EXECUTION OPPORTUNITY DETECTED
   
   The following artifact groups can be generated in parallel:
   
   Group 1: Code Implementation
   - PaymentRetryClient.ts
   - PaymentRetryQueue.ts
   - IdempotencyService.ts
   - CircuitBreaker.ts
   
   Group 2: Test Files
   - PaymentRetryClient.test.ts
   - IdempotencyService.test.ts
   - integration.test.ts
   
   Group 3: Documentation & Ops
   - README.md, API.md, DECISIONS.md
   - Runbooks, Dashboards, Alerts
   
   Estimated speedup: 2.5x
   Confidence: 85%
   
   Would you like to generate artifacts in parallel using git worktrees?
   [Y]es / [N]o / [D]etails
   

4. If Approved: Use /manifold:parallel command to execute generation in isolated worktrees

5. If Declined: Proceed with sequential generation

Parallel Generation Flow

User runs: /manifold:m4-generate payment-retry --option=C

1. Parse manifold and anchoring
2. Build artifact generation plan
3. Analyze for parallelization (≥3 independent groups?)
   └── YES: Invoke auto-suggester
       └── Suggestion positive?
           └── YES: Prompt user for approval
               └── Approved: Use /manifold:parallel for generation
               └── Declined: Sequential generation
           └── NO: Sequential generation
   └── NO: Sequential generation
4. Generate artifacts (parallel or sequential)
5. Merge results and update manifold

Execution Instructions

⚡ STEP 0: Binding Constraint Check (MANDATORY)

Before any planning or generation, read anchors.binding_constraint from .manifold/<feature>.json.

If present:

• Display: BINDING CONSTRAINT: [RT-ID] — [reason]
• Artifacts satisfying the binding constraint's required truth MUST be generated FIRST
• Tag these artifacts in the generation summary: ⚡ Binding constraint
• If the binding constraint's RT has unresolved evidence after generation, WARN before completing m4

If absent: proceed normally (backward compatible with pre-enhancement manifolds).

Phase 1: Planning (BEFORE any file writes)

1. Read manifold from .manifold/<feature>.json (or .yaml for legacy)
2. Read anchoring from JSON anchors section (or .manifold/<feature>.anchor.yaml for legacy)
3. Select solution option (from --option or prompt user)
4. BUILD ARTIFACT LIST - List ALL files that will be generated, ordered by binding constraint priority
5. MANDATORY PARALLELIZATION CHECK (See "STEP 0" above)
   • Count the artifact groups (code, tests, docs, ops)
   • If ≥3 files across different directories:

     PARALLEL GENERATION OPPORTUNITY
     
     I've identified [N] artifacts that could be generated in parallel:
     
     Group 1 - [Type]: [file1, file2, ...]
     Group 2 - [Type]: [file1, file2, ...]
     Group 3 - [Type]: [file1, file2, ...]
     
     Estimated speedup: ~Xx faster
     
     Would you like to enable parallel generation? [Y/N]
     

   • WAIT for user response before proceeding
   • If Y: Use /manifold:parallel command with generation tasks
   • If N: Continue with sequential generation

Phase 2: Generation (AFTER user approval)

6. CHECK PROJECT PATTERNS - Examine existing structure before placing files
7. For each artifact type:
   • Generate artifact with constraint traceability
   • Add comments linking to constraint IDs: // Satisfies: B1, T2
   • For test files, include @constraint annotations so m5-verify can build the traceability matrix:

     // @constraint B1 - No duplicate payments
     it('rejects duplicate payment attempts', async () => { ... });
     

   • Place in correct directory per Artifact Placement Rules
8. Create all files in appropriate directories
9. Update install script if adding new distributable commands 9b. If --prd flag: Generate docs/<feature>/PRD.md using the PRD Generation section below. Map constraints to PRD sections per the Constraint-to-PRD Mapping Rules. 9c. If --stories flag: Generate docs/<feature>/STORIES.md using the User Story Generation section below. Derive stories from UX constraints, cross-reference PRD if both flags are set.

Phase 3: Finalization

10. Update manifold with generation tracking (artifacts, coverage)

    • JSON+MD: Update .manifold/<feature>.json with generation section
    • Legacy YAML: Update .manifold/<feature>.yaml

11. Populate evidence arrays on all required truths with concrete, verifiable evidence items (file_exists, content_match, test_passes, manual_review) 11b. Immediate Evidence Validation — After populating evidence, validate what CAN be checked now:

    • file_exists: Check the file exists on disk. If missing → flag as GENERATION_FAILED
    • content_match: Grep the pattern in the file. If no match → flag as CONTENT_MISMATCH
    • test_passes: Leave as PENDING (requires execution, m5's job)
    • manual_review: Leave as PENDING (requires human) Surface any failures immediately — do NOT defer all evidence checking to m5. This catches generation errors (wrong paths, missing patterns) while context is fresh.

12. Set artifact_class on every artifact in the generation section (substantive or structural)

13. Verify invariant evidence: For invariant-type constraints, ensure at least one test_passes evidence exists via the RT maps_to chain or directly via verified_by

14. Set phase to GENERATED

15. MANDATORY POST-GENERATION VALIDATION

    manifold validate <feature>
    

    • If validation fails, fix the errors BEFORE proceeding
    • JSON+MD format: Ensure JSON IDs match Markdown headings, constraint IDs follow patterns (B1, T1, U1, S1, O1)
    • Legacy YAML: Constraints use statement, tensions use description
    • See SCHEMA_QUICK_REFERENCE.md for field mappings
    • Schema reference: install/manifold-structure.schema.json

    Format lock: If .manifold/<feature>.json exists, ALWAYS use JSON+Markdown format. Never create/update .yaml when .json exists.

16. Display summary with constraint coverage

PRD Generation (--prd flag)

When --prd is specified, generate an industry-standard Product Requirements Document from the manifold.

PRD Output Location

docs/<feature>/PRD.md

PRD Structure (13 Sections + Appendices)

# PRD: [Feature Name]

| Field | Value |
|-------|-------|
| **Author** | [From manifold meta or "Product Manager"] |
| **Status** | Draft / In Review / Approved |
| **Created** | [timestamp] |
| **Last Updated** | [timestamp] |
| **Manifold** | `.manifold/<feature>.json` |

## 1. Problem Statement
[Generated from: outcome + business constraint rationale]
**Who is affected:** [from UX constraints context]
**Current impact:** [from business constraints with baselines]
**Why now:** [from timeline/boundary constraints]

## 2. Business Objectives
[Generated from: business GOAL constraints + outcome]
- **Strategic alignment:** [from B-constraints rationale]
- **Success criteria:** [measurable targets from GOALs]

## 3. Success Metrics

| Metric | Target | Baseline | Constraint |
|--------|--------|----------|------------|
| [name] | [target] | [current] | [ID] |

[Generated from: GOAL type constraints with measurable criteria]

## 4. Target Users & Personas
[Generated from: user_experience constraints context + "As a" patterns]

### Persona 1: [User Type]
- **Needs:** [from UX constraint statements]
- **Pain Points:** [from UX constraint rationale]
- **Key Workflows:** [from UX boundaries]

## 5. Assumptions & Constraints
**Assumptions:**
[Generated from: technical constraints with "assumes", security compliance refs]

**Constraints:**
[Generated from: ALL boundary-type constraints across categories]

## 6. Requirements (MoSCoW)

### Must Have (Invariants)
[All constraints.*.type: invariant]
- **[statement]** ([ID]) — [rationale]
  - _Traces to: [related IDs]_

### Should Have (Boundaries)
[All constraints.*.type: boundary]
- **[statement]** ([ID]) — [rationale]

### Could Have (Goals)
[All constraints.*.type: goal, excluding success metrics]
- **[statement]** ([ID]) — [rationale]

### Won't Have (This Release)
[Generated from: _customization.common_removals]

## 7. User Flows & Design
[Generated from: UX constraints describing workflows + required truths about user journeys]

## 8. Out of Scope
[Generated from: _customization.common_removals + explicit exclusions]

## 9. Risks & Mitigations

| Risk | Severity | Source | Mitigation |
|------|----------|--------|------------|
| [description] | High/Med/Low | [ID] | [resolution] |

[Generated from: resolved tensions + security constraints]

## 10. Dependencies

| Dependency | Type | Owner | Status |
|------------|------|-------|--------|
| [description] | Internal/External | [team] | Pending/Ready |

[Generated from: technical constraints with "depends on", "requires", "integrates with"]

## 11. Timeline & Milestones

| Milestone | Date | Dependencies |
|-----------|------|--------------|
| [name] | [date] | [items] |

[Generated from: boundary constraints with timeline + operational constraints]

## 12. Open Questions

| # | Question | Impact | Decision Needed By |
|---|----------|--------|-------------------|
| 1 | [question] | [constraint IDs] | [date] |

[Generated from: unresolved tensions + anchors.open_questions]

---

## Appendix A: Constraint Traceability Matrix

| PRD Section | Constraint IDs |
|-------------|---------------|
| Problem Statement | B1, B2 |
| Success Metrics | B2, B4 |
| Must Have | B1, T2, S1, ... |
| ... | ... |

## Appendix B: Manifold Reference
_Generated from `.manifold/<feature>.json` + `.manifold/<feature>.md`_
_Schema version: [version]_
_Phase: [phase]_
_Constraint coverage: [X]/[Y] constraints addressed_

Constraint-to-PRD Mapping Rules

PRD Generation Example

Input manifold (JSON+MD):

.manifold/checkout-redesign.json (structure):

{
  "constraints": {
    "business": [
      { "id": "B1", "type": "invariant" },
      { "id": "B2", "type": "goal" }
    ],
    "user_experience": [
      { "id": "U1", "type": "boundary" }
    ]
  },
  "tensions": [
    { "id": "TN1", "type": "trade_off", "between": ["B2", "T1"], "status": "resolved" }
  ]
}

.manifold/checkout-redesign.md (content):

## Outcome
Increase checkout conversion by 15%

### Business
#### B1: Protect Existing Checkout
Must not disrupt existing checkout.
> **Rationale:** Revenue protection during transition.

#### B2: Conversion Target
Increase conversion by 15%.
> **Rationale:** Mobile is 60% of traffic.

### User Experience
#### U1: Checkout Steps
Maximum 3 clicks to complete.
> **Rationale:** Each step adds abandonment risk.

## Tensions
### TN1: Conversion Goal vs Capacity
> **Resolution:** Phased rollout.

Generated PRD excerpt:

## 1. Problem Statement
Increase checkout conversion by 15% while maintaining existing checkout stability.
**Who is affected:** Mobile shoppers (60% of traffic)
**Why now:** Revenue protection during transition period

## 2. Business Objectives
- **Strategic alignment:** Maximize mobile conversion opportunity
- **Success criteria:** 15% improvement in checkout conversion rate

## 3. Success Metrics
| Metric | Target | Baseline | Constraint |
|--------|--------|----------|------------|
| Checkout conversion | +15% | Current rate | B2 |

## 6. Requirements (MoSCoW)

### Must Have (Invariants)
- **Must not disrupt existing checkout** (B1) — Revenue protection during transition
  - _Traces to: B1_

### Should Have (Boundaries)
- **Maximum 3 clicks to complete** (U1) — Each step adds abandonment risk
  - _Traces to: U1_

## 9. Risks & Mitigations
| Risk | Severity | Source | Mitigation |
|------|----------|--------|------------|
| Conversion goal vs capacity | Medium | TN1 | Phased rollout |

PRD Artifact Tracking

After PRD generation, update .manifold/<feature>.json:

{
  "generation": {
    "artifacts": [
      {
        "path": "docs/<feature>/PRD.md",
        "type": "prd",
        "satisfies": ["B1", "B2", "T1", "U1", "S1", "O1"],
        "status": "generated"
      }
    ]
  }
}

User Story Generation (--stories flag)

When --stories is specified, generate user stories with acceptance criteria from the manifold.

Stories Output Location

docs/<feature>/STORIES.md

Stories Structure

# User Stories: [Feature Name]

_See also: [PRD](PRD.md) for business context and full requirements_

## Epic: [Outcome statement]

### US-1: [Story title derived from U1 statement]
**As a** [user type - derived from PRD Section 4: Target Users & Personas]
**I want** [capability - action verb from constraint statement]
**So that** [value - from constraint rationale]

**Priority:** P0/P1/P2
**Estimate:** [story points placeholder - to be estimated by team]

**Acceptance Criteria:**
- [ ] [Derived from constraint statement]
- [ ] [Derived from related boundary constraint]
- [ ] [Derived from required truth if mapped]

**Traces to:** [constraint IDs]
**PRD Sections:** [cross-reference to relevant PRD section numbers]

---

### US-2: [Story title derived from U2]
...

---

## Story Map

| Priority | Story | Constraints | Dependencies | Estimate | Status |
|----------|-------|-------------|--------------|----------|--------|
| P0 | US-1 | U1, B2 | - | - | Ready |
| P1 | US-2 | U2, T3 | US-1 | - | Blocked |

## Dependencies Graph

```mermaid
graph TD
    US1[US-1: Title] --> US2[US-2: Title]
    TN1{Tension: Description} -.-> US1

Generated from .manifold/<feature>.json + .manifold/<feature>.md Cross-references: PRD

### Constraint-to-Story Transformation Rules

| Source | Story Field | Transformation |
|--------|-------------|----------------|
| `constraints.user_experience` | One story per UX constraint | Primary source |
| Constraint statement | "I want" clause | Extract action verb, user-facing language |
| Constraint rationale | "So that" clause | Focus on value/outcome |
| PRD Section 4 (Personas) | "As a" clause | Use persona from PRD; fallback to constraint context or default "user" |
| Related constraints | Acceptance criteria | One criterion per related constraint |
| `anchors.required_truths` | Acceptance criteria | If maps_to_constraints includes this story's source |
| Boundary constraints | Acceptance criteria | Measurable thresholds |
| `tensions` | Dependencies | Tensions between story constraints |
| PRD Section numbers | PRD Sections field | Cross-reference to relevant PRD sections |

### Story Priority Rules

| Constraint Type | Default Priority | MoSCoW (PRD Section 6) |
|-----------------|------------------|------------------------|
| Invariant-related | P0 (must have) | Must Have |
| Boundary-related | P1 (should have) | Should Have |
| Goal-related | P2 (nice to have) | Could Have |

### Story Dependencies from Tensions

```json
{
  "tensions": [
    {
      "id": "TN1",
      "type": "trade_off",
      "between": ["U1", "U2"],
      "status": "resolved",
      "decision": "A"
    }
  ]
}

Then in STORIES.md, tension-driven dependencies become:

| Priority | Story | Dependencies | Estimate |
|----------|-------|--------------|----------|
| P0 | US-1 (from U1) | - | - |
| P1 | US-2 (from U2) | US-1 | - |

Stories Generation Example

Input manifold (JSON+MD):

.manifold/checkout-redesign.json (structure):

{
  "constraints": {
    "user_experience": [
      { "id": "U1", "type": "boundary" },
      { "id": "U2", "type": "goal" }
    ],
    "business": [
      { "id": "B1", "type": "invariant" }
    ]
  },
  "anchors": {
    "required_truths": [
      { "id": "RT-1", "status": "NOT_SATISFIED", "maps_to": ["U1", "B1"] }
    ]
  }
}

.manifold/checkout-redesign.md (content):

#### U1: Quick Checkout
User can complete checkout in 3 steps or fewer.
> **Rationale:** Simplicity drives conversion.

#### U2: Self-Service Success
First-time users succeed without help.
> **Rationale:** Self-service reduces support burden.

#### B1: No Conversion Regression
No conversion regression.

### RT-1: Error-Free Purchase
User completes purchase without errors.

Generated stories:

### US-1: Quick Checkout Flow
**As a** mobile shopper _(from PRD Persona 1)_
**I want** to complete checkout in 3 steps or fewer
**So that** I can purchase quickly (simplicity drives conversion)

**Priority:** P1 (boundary)
**Estimate:** _To be estimated by team_

**Acceptance Criteria:**
- [ ] Checkout completes in ≤3 steps (U1)
- [ ] No conversion regression from baseline (B1)
- [ ] User completes purchase without errors (RT-1)

**Traces to:** U1, B1, RT-1
**PRD Sections:** 4 (Target Users), 6 (Requirements), 7 (User Flows)

Combined Flag Support

When both --prd and --stories are specified:

/manifold:m4-generate payment-checkout --option=C --prd --stories

Generates:

• docs/payment-checkout/PRD.md
• docs/payment-checkout/STORIES.md

Both files cross-reference each other:

• PRD Section 6 (Requirements) links to stories for detailed user requirements
• Stories link back to PRD sections for business context, personas, and user flows

Stories Artifact Tracking

After stories generation, update .manifold/<feature>.json:

{
  "generation": {
    "artifacts": [
      {
        "path": "docs/<feature>/PRD.md",
        "type": "prd",
        "satisfies": ["B1", "B2", "T1", "U1", "S1", "O1"],
        "status": "generated"
      },
      {
        "path": "docs/<feature>/STORIES.md",
        "type": "stories",
        "satisfies": ["U1", "U2", "U3", "U4"],
        "status": "generated"
      }
    ]
  }
}

Interaction Rules (MANDATORY)

1. Questions → AskUserQuestion: When you need user input during this phase, use the AskUserQuestion tool with structured options. NEVER ask questions as plain text without options.
2. Phase complete → Suggest next: After completing this phase, ALWAYS include the concrete next command (/manifold:mN-xxx <feature>) and a one-line explanation of what the next phase does.
3. Trade-offs → Labeled options: When presenting alternatives, use AskUserQuestion with labeled choices (A, B, C) and descriptions.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.