proposal review

APEX Workflow Revisions Proposal

Robert Matsuoka Updated 2026-03-11
apex workflow process github-issues

APEX Workflow Revisions Proposal

Document Classification: Process Proposal Status: REVIEW Created: 2026-03-05 Updated: 2026-03-06 Author: Robert Matsuoka (CTO) Reviewers: Kartik Yellepeddi (CPO)

Summary

This proposal defines revisions to the APEX workflow chain:

Initiative → PRD → Implementation Plan → Ticket Generation

It does not cover tooling, infrastructure, integrations, or analytics — those are separate concerns.

1. Initiative Creation

Problem

Initiatives are frequently created without identifying the target user role, making downstream PRD and ticket generation less precise.

Proposed Change: Add Target User Field

One new required field is added to the apex-initiative workflow:

Field Options
Who is the target user? CCO, CFO, VP_DIST, VP_RM, VP_SALES, ASSET_MGR, IT_DIR, CONTROLLER, DIST_MGR, DOC, DOS, GM, PROP_RM, CLUSTER_RM, DORM, DIR_ANCILLARY, VP_CASINO

This field is required and non-skippable. It populates the target_user frontmatter field directly.

Note: Customer segment (asset_type_target) and community enhancement request tracking (enhancement_request) are already captured as part of PR #23 (business context fields). Ticket platform context is covered via the contractual_commitment field added in that PR. These are not duplicated here.

Claude (via apex-initiative) surfaces existing similar initiatives before creating a new one.

Acceptance Criteria

  • [ ] Cannot create an initiative without selecting a target user role
  • [ ] Similar existing initiatives are surfaced before creation completes
  • [ ] target_user frontmatter is auto-populated — no manual editing required

2. Initiative → PRD Transition

Problem

PRDs are sometimes generated before a hypothesis has been properly tested, resulting in low-quality specs.

Proposed Change: Risk-Based Experiment Gate

The apex-prd skill warns (but does not hard-block) if no completed experiments exist. Teams that have assessed and accepted the risk may proceed without experiments.

Gate behaviour: - If no completed experiments exist → apex-prd warns and asks the team to confirm they are accepting the risk of proceeding without validation - If at least one completed experiment exists with a non-empty learning section → proceeds without warning - Initiative status must be validated before PRD generation; apex-prd blocks (hard) if status is still discovery

Rationale: Experiments are not mandatory — they are only required when the team judges there is meaningful hypothesis risk. The gate enforces intent, not process bureaucracy.

PRD Template Changes

PRDs generated from an initiative auto-populate: - validated_experiments — list of completed experiment IDs (empty array if none) - target_user — from initiative frontmatter - hypothesis_summary — synthesized from experiment learnings by Claude (or from hypothesis if no experiments)

Acceptance Criteria

  • [ ] apex-prd hard-blocks if initiative status is discovery
  • [ ] apex-prd warns (not blocks) if no completed experiments exist, requiring explicit confirmation
  • [ ] PRD frontmatter is auto-populated from initiative context
  • [ ] Human reviews and approves the generated PRD before status advances to approved

3. PRD → Implementation Plan

Problem

There is no standard artifact connecting an approved PRD to the work that executes it. Engineers go directly from PRD to ad-hoc work.

Proposed Change: Implementation Plan Generation

When a PRD reaches approved status, apex-prd (or a new apex-plan skill) triggers generation of an implementation plan. The plan is a human-reviewed artifact, not auto-executed.

PRD and plan alignment: If a feature requires multiple phases, the PRD should be split before plan generation — one PRD per phase, one implementation plan per PRD. This keeps plans actionable and diffs reviewable.

Generation process:

  1. PRD approval triggers plan generation — Claude reads the PRD and produces a draft implementation plan
  2. Plan includes:
  3. Repository identification (which repos are touched)
  4. Sequencing of work (dependencies between tasks)
  5. Acceptance criteria per task (derived from PRD success criteria)
  6. Suggested ticket breakdown
  7. Tech lead approval gate — the plan is a draft until the tech lead approves it; PM is a non-blocking reviewer
  8. Dry run mode — the plan can be previewed without committing to tickets

Implementation Plan frontmatter:

id: PLAN-YYYY-XX-NNN
prd_id: PRD-YYYY-XX-NNN
status: draft | approved | in-progress | complete
repos: []
approved_by: ~        # tech lead
reviewed_by: ~        # PM (non-blocking)
approved_date: ~

Acceptance Criteria

  • [ ] PRD approval triggers draft implementation plan generation
  • [ ] Plan identifies affected repositories
  • [ ] Tech lead approval required before tickets are created
  • [ ] PM review is recorded but does not block ticket generation
  • [ ] Dry run mode shows what would be created without executing
  • [ ] Multi-phase features require PRD to be split before plan generation

4. Implementation Plan → Ticket Generation

Problem

Tickets are created manually and inconsistently, with variable quality and no traceability back to the PRD or initiative.

Proposed Change: Ticket Generation from Approved Plan

Once the implementation plan is approved, apex-epic generates GitHub Issues automatically.

Workflow:

Approved Implementation Plan
        ↓
  apex-epic (dry run) → human reviews proposed tickets
        ↓ approve
  GitHub Issues created (Epic as milestone, stories as issues)
        ↓
  Epic ID written back to implementation plan frontmatter

Ticket structure generated: - One GitHub milestone per implementation plan (serves as the Epic) - Issues decomposed from the plan's task list - Each issue includes: acceptance criteria, repo reference, PRD link, initiative link - Issues are sequenced per the plan's dependency order

Traceability chain written into each ticket:

Initiative: I-YYYY-XX-NNN
PRD: PRD-YYYY-XX-NNN
Plan: PLAN-YYYY-XX-NNN

Acceptance Criteria

  • [ ] Dry run previews all tickets before creation
  • [ ] Each ticket has traceability back to initiative, PRD, and plan
  • [ ] Milestone ID written back to implementation plan on creation
  • [ ] Issues are sequenced per dependency order in the plan

5. PRD → Code (Post-Ticket)

From the 2026-03-05 kickoff discussion, the workflow continues past ticket generation:

Tickets Created
      ↓
AI code generation + human review  (per-ticket, per-repo)
      ↓
QA plan auto-generation + human approval
      ↓
Deploy → Test → Release

Key design decisions: - Code generation is per-ticket, not per-PRD — keeps diffs reviewable - QA plans are generated from acceptance criteria in the implementation plan - Human approval required at: implementation plan, code review, QA plan, release

This phase is noted here for completeness. A separate proposal will define the code generation and QA automation workflow in detail once ticket generation is stable.

Decisions Recorded

# Question Decision
1 Ticket platform GitHub Issues — milestone as epic, issues as stories
2 Who approves implementation plans? Tech lead (blocking) + PM (non-blocking reviewer)
3 Experiment gate strictness Risk-based — warn and confirm if no experiments, hard-block only if status is still discovery
4 Plan granularity One plan per PRD — split the PRD if a feature spans multiple phases

Document Status: REVIEW Reference: APEX-WORKFLOW-REVISIONS-SPEC.md