User Flow Map - AFPS Tracker

Scope And Sources

The proposed flow maps the first real repo read-through: an operator opens AFPS Tracker on an existing AFPS repository, sees active and parallel product paths, verifies stage/provenance/evidence links against source artifacts, and leaves able to resume the correct next research step or answer why a branch exists.

Explicit Non-Goals

Generic PM workflows, development execution tracking, autonomous recommendations or nudges, production architecture, database schema, high-fidelity UI, replacing AFPS skills or canonical AFPS artifacts, write-back as first success, and continuing promoted branch development inside AFPS Tracker.

Assumptions And Coverage

Flow Map

Persona, Goal, And Success

The primary persona is an AFPS operator who manages repo-local AFPS artifacts across research, design, approval, and future handoff sessions. Their goal is to understand the product-path portfolio without reconstructing state from scattered markdown, YAML, alignment pages, archives, and task logs. First success is read-first trust: the displayed path state, evidence, approval provenance, freshness, and parser confidence are clear enough to resume the correct next AFPS command or answer a branch-state question.

Happy Path

Entry Points And Preconditions

Entry points are direct repo/project open, session-resume prompt, alignment/progress follow-through, and branch-state review. Preconditions are an AFPS-style repository, canonical state in repo-local files, source-truth subordination, visible handling for missing/stale/inaccessible/low-confidence sources, and an empty/no-path state when no product paths exist.

Alternate Paths And Decisions

Alternate paths cover single-path, multi-path, empty/no product paths, stale artifacts, missing artifacts, permission-denied file access, parser uncertainty, evidence deep-dive, quick scan, archived/deferred/revisit/promoted states, and future gated-edit intent. User decisions include entry path, selected product path, evidence depth, trust level, and whether edit intent is parked. System decisions include AFPS artifact detection, active/excluded path classification, state derivation, freshness/parser confidence, evidence resolution, and promoted-boundary handoff.

Surface Inventory

Low-Fidelity Notes

S1 groups product paths by state with source-health badges. S2 separates source-backed fields from derived fields. S3 shows path/source status and claim mapping. S4 separates approvals, canonical writes, archives, and unresolved gaps. S5 puts blocking failures first and keeps diagnostics claim-scoped. S6 defaults to concise copyable summary with expandable evidence-backed mode.

Action And State Matrix

Each surface supports inspection, navigation to affected evidence/provenance/diagnostics, disabled controls when trust is insufficient, validation against source paths and fields, and audit records for what source contributed to the displayed result.

Clean handoff is disabled for blocking diagnostics. Copy-with-warnings is allowed only when warnings are embedded in the copied payload. Promoted or inactive paths produce explanatory boundary output rather than active next-command routing.

Failures And Recovery

The governing rule is source-preserving degradation: keep source-backed claims visible, label unsupported or inferred claims explicitly, and block only actions whose trust requirements are not met.

Handoffs

Structured Handoff Shape

path_id: afps-tracker
label: AFPS Tracker
state: active
pipeline_stage: positioning
next_skill: "$user-flow-map research/afps-tracker"
handoff_type: next-afps-skill | future-self | agent-session | evidence-review | diagnostics-correction | inactive-explanation | promoted-boundary | out-of-scope
confidence: clean | warning | blocked | explanatory | out-of-scope
branch_state_explanation: "Source-backed explanation of why this path has its current state."
evidence_refs: []
provenance_refs: []
warnings: []
blocked_reasons: []
handoff_boundary: "research-flow | source-correction | execution-tracker | out-of-scope"
source_paths: []
generated_at: "repo-local scan timestamp when available"

Flow-Tree Branches

Branches are ordered by journey progression: orientation before verification, verification before recovery and handoff, and inactive/promoted explanations where they naturally occur.

Interview Log Preview

Evidence consulted: project config and AGENTS instructions, approved AFPS Tracker idea brief, ICP, competitive analysis, journey map, positioning synthesis, glossary, progress manifest, Round 1 interrogation sidecar, shared chunked setup brief, and all four chunk intermediates.

Round 1 assumptions were all confirmed. Open answers selected the first real repo read-through as the primary flow; required entry points were repo open, session restart/compaction, alignment/progress follow-through, and branch-state review; likely surfaces were the six listed above; required states included empty, loading, error, partial, success, permission-denied, offline/local-only, validation, archived/deferred/revisit/promoted states, and promoted-path handoff out of AFPS Tracker scope.

Coverage checkpoint was confirmed with no missing branch, state, handoff, or boundary. No branch-order override was requested; journey progression order is used.

Manifest

This is the approved flow-tree root written to design/afps-tracker/flow-tree-afps-tracker.yaml.

schema_version: v0.4
mode: product-path
topic: afps-tracker
product_path: research/afps-tracker
route:
  - user-flow-map
  - ux-variations
  - ui-interview
  - logic-wiring
  - consolidate-prototypes
  - spec-interview
source_artifacts:
  - research/afps-tracker/idea-brief.md
  - research/afps-tracker/icp.md
  - research/afps-tracker/competitive-analysis.md
  - research/afps-tracker/journey-map.md
  - research/afps-tracker/positioning.md
  - research/afps-tracker/glossary.md
  - research/.progress.yaml
  - research/afps-tracker/_working/interrogation-user-flow-map-r1.yaml
  - design/afps-tracker/_working/user-flow-map-afps-tracker-brief.md
branches:
  - id: uf-orient-portfolio
    name: Orient To Product Portfolio
    status: pending
    journey_stage: activation
    journey_sequence: 10
    priority_rationale: Earliest context recovery before selected-path trust work.
    progressive_review:
      first_value_moment: Operator sees active and parallel paths without manual file reading.
      primary_task_path: Open tracker, scan portfolio, select path.
      sequence: 1
  - id: uf-verify-selected-path
    name: Verify Selected Product Path
    status: pending
    journey_stage: first-value
    journey_sequence: 20
    priority_rationale: Core first-value branch and highest trust risk.
    progressive_review:
      first_value_moment: Operator trusts selected path stage, status, reason, evidence, provenance, and next skill.
      primary_task_path: Select path, inspect detail, verify evidence and provenance.
      sequence: 2
  - id: uf-inspect-source-provenance
    name: Inspect Source And Provenance
    status: pending
    journey_stage: first-value
    journey_sequence: 30
    priority_rationale: Converts summary state into verifiable source-backed state.
    progressive_review:
      first_value_moment: Operator can trace displayed claims to source docs and approval lineage.
      primary_task_path: Open evidence inspector and provenance view.
      sequence: 3
  - id: uf-recover-diagnostics
    name: Recover From Diagnostics
    status: pending
    journey_stage: recovery
    journey_sequence: 40
    priority_rationale: Prevents false confidence under stale, missing, contradictory, or unreadable sources.
    progressive_review:
      first_value_moment: Operator knows what remains usable, warning-level, or blocked.
      primary_task_path: Review diagnostics and route to source verification.
      sequence: 4
  - id: uf-handoff-resume
    name: Resume Or Export Handoff
    status: pending
    journey_stage: handoff
    journey_sequence: 50
    priority_rationale: Completes the read-first flow once trust is established.
    progressive_review:
      first_value_moment: Operator leaves with next command or branch-state answer preserving evidence and warnings.
      primary_task_path: Generate handoff summary and copy/export if allowed.
      sequence: 5
  - id: uf-explain-boundaries
    name: Explain Inactive Or Promoted Boundaries
    status: pending
    journey_stage: handoff
    journey_sequence: 60
    priority_rationale: Preserves AFPS Tracker scope and keeps execution tracking separate.
    progressive_review:
      first_value_moment: Operator can explain inactive, promoted, or out-of-scope branches without misleading routing.
      primary_task_path: Inspect inactive/promoted path and generate explanatory boundary handoff.
      sequence: 6

Approval Record

Final Compiled Response YAML Summary

# Invoke with: $user-flow-map research/afps-tracker
command: "$user-flow-map research/afps-tracker"
alignment_page: alignment/user-flow-map-afps-tracker.html
response_status: "complete"
approval_status: "ready-for-agent-review"
required_gate_status: "complete"
unanswered_required_questions: []
gate_answers:
  - section: "Canonical flow map"
    gate_type: required
    status: "answered"
    answer: "approve"
    target_path: "design/afps-tracker/user-flow-afps-tracker.md"
    notes: ""
  - section: "Interview log"
    gate_type: required
    status: "answered"
    answer: "approve"
    target_path: "design/afps-tracker/user-flow-afps-tracker-interview.md"
    notes: ""
  - section: "Flow-tree manifest"
    gate_type: required
    status: "answered"
    answer: "approve"
    target_path: "design/afps-tracker/flow-tree-afps-tracker.yaml"
    notes: ""