User Flow Map - AFPS Tracker
Review page for the proposed AFPS Tracker first real repo read-through flow. Canonical design files are not written yet; approval from this page authorizes writing the flow map, interview log, and flow-tree manifest.
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
| Area | Source | Decision | Carried Into Flow |
|---|---|---|---|
| Primary persona | Positioning | Confirmed | AFPS power user / AI workflow operator. |
| Product job | Journey map | Confirmed | Source-linked read-through across AFPS artifacts. |
| Entry triggers | Journey map | Confirmed | Repo open, restart/compaction, alignment/progress follow-through, branch-state question. |
| First success | Journey map | Confirmed | Read-first trust sufficient to resume or explain state. |
| Product boundary | Idea brief | Confirmed | Passive tracker over AFPS source truth. |
| Read-first behavior | Positioning | Confirmed | No silent correction or duplicate tracker truth. |
| Likely surfaces | Inference from research | Confirmed | Six visual candidate surfaces plus structured diagnostic/handoff payloads. |
Coverage Gate Result
Coverage checkpoint was confirmed by the user before this page was built. No additional missing branch, state, handoff recipient, or boundary was flagged.
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
| ID | Surface | Purpose | Channels | Visual Candidate | Downstream |
|---|---|---|---|---|---|
| S1 | Portfolio Overview | Show discovered product paths and portfolio state. | Web UI; future CLI/MCP/API summary. | Yes | S2, S5, S6 |
| S2 | Product-Path Detail | Explain one path's state, stage, reason, evidence, provenance, and next skill. | Web UI; structured detail response. | Yes | S3, S4, S5, S6 |
| S3 | Evidence/Source Inspector | Verify a displayed claim against canonical files or source hints. | Web source inspector; file-open/CLI/MCP ref response later. | Yes | S2, S5, S6 |
| S4 | Alignment/Provenance View | Show approval lineage and decision history. | Web provenance timeline; audit/CLI/MCP response later. | Yes | S2, S3, S6 |
| S5 | Freshness And Parser Diagnostics | Expose trust limits, missing files, stale refs, permission failures, and inferred facts. | Web diagnostics; validation result; audit record; CLI/MCP/API payload. | Yes plus non-visual | S1-S4, S6 |
| S6 | Export Or Handoff Summary | Give handoff-ready next command or branch-state answer. | Web copy/export; future text, CLI/MCP/API response, audit record. | Yes plus non-visual | Terminal read-first surface |
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.
| State | Required Treatment |
|---|---|
| Empty | Show source checked, avoid invented paths, provide read-only diagnostic context. |
| Loading | Distinguish prior loaded state from current scan; do not present stale results as freshly verified. |
| Error | Name affected source and claims; preserve unaffected surfaces where possible. |
| Partial | Label missing fields, evidence refs, provenance records, and confidence limits at field and path level. |
| Success | Allow quick scan and handoff when facts are source-backed or clearly derived with no blocking diagnostics. |
| Permission-denied | Name affected path, suppress unsupported claims, preserve other readable sources. |
| Offline/local-only | Keep repo-local read-through functional; external browsing is not required for v1 success. |
| Validation | Expose schema, parser, evidence-link, provenance, and freshness warnings beside affected claims. |
| Edge states | Archived, deferred, revisit-candidate, promoted, out-of-scope, stale, unsupported, inferred, and contradictory states remain visible as portfolio context. |
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.
| Failure Class | Recovery | Handoff Impact |
|---|---|---|
| No manifest or empty paths | Show empty/no-manifest or unresolved-active state with checked source path. | No clean next command unless source fields provide one. |
| Invalid YAML/schema or missing required fields | Block malformed-derived claims, show affected fields, preserve separately readable artifacts. | Clean handoff disabled or warning-only copy. |
| Missing scope path, evidence ref, or provenance artifact | Keep unresolved refs visible, lower confidence, preserve readable source-backed facts. | Handoff includes unresolved refs and confidence caveats. |
| Permission denied | Name inaccessible path and suppress unsupported claims from that source. | Clean handoff disabled when inaccessible source supports selected state. |
| Stale, low-confidence, or contradictory source | Show affected claims, avoid silently choosing the newer value, route to source verification. | Next-command handoff blocked or copied only with explicit warning. |
| Write-back or out-of-scope request | Park as future gated intent outside read-first v1; name owning artifact/skill when known. | No mutation or write-back handoff from AFPS Tracker. |
| Promoted path | Show research-state explanation and promotion basis, then hand off to separate execution-tracker concept. | No normal AFPS research continuation. |
Handoffs
| ID | Handoff | Recipient | Completion |
|---|---|---|---|
| H1 | Next AFPS Skill Resume | Same operator | Operator runs or queues the next AFPS skill command with source context preserved. |
| H2 | Future-Self Resume | Future operator | Future self can answer what is current and why without reconstructing from scratch. |
| H3 | Agent Session Handoff | Codex/Claude session | New agent can resume or verify named sources without widening scope. |
| H4 | Evidence Review Handoff | Collaborator, client, reviewer | Reviewer understands branch state, strong evidence, weak evidence, and gaps. |
| H5 | Diagnostics/Correction Handoff | Operator or owning AFPS skill/source artifact | Operator verifies or corrects canonical source outside the read-first viewer. |
| H6 | Inactive Branch Explanation | Operator, future self, collaborator, or agent | Recipient gets branch-state answer without misleading active next command. |
| H7 | Promoted Branch Boundary | Operator and separate execution tracker | AFPS Tracker ends at research promotion and does not absorb development tracking. |
| H8 | Out-Of-Scope Request | Operator | Operator understands why read-first flow stops and where separate work belongs. |
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.
| Branch ID | Name | Stage | Seq | First Value Moment | Priority Rationale |
|---|---|---|---|---|---|
| uf-orient-portfolio | Orient To Product Portfolio | activation | 10 | Operator sees active and parallel paths without manual file reading. | Earliest context recovery; required before path-specific trust work. |
| uf-verify-selected-path | Verify Selected Product Path | first-value | 20 | Operator trusts selected path's stage, status, reason, evidence, provenance, and next skill. | Core first-value branch and highest trust risk. |
| uf-inspect-source-provenance | Inspect Source And Provenance | first-value | 30 | Operator can trace claims to source docs and confirmed approval lineage. | Turns summary into verifiable source-backed state. |
| uf-recover-diagnostics | Recover From Diagnostics | recovery | 40 | Operator knows what remains usable, warning-level, or blocked. | Prevents false confidence when sources are missing, stale, contradictory, or unreadable. |
| uf-handoff-resume | Resume Or Export Handoff | handoff | 50 | Operator leaves with next command or branch-state answer that preserves evidence and warnings. | Completes the read-first flow once trust has been established. |
| uf-explain-boundaries | Explain Inactive Or Promoted Boundaries | handoff | 60 | Operator can explain inactive/promoted/out-of-scope branches without misleading active routing. | Preserves AFPS Tracker scope and keeps execution tracking separate. |
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 Preview
This is the proposed flow-tree root that will be written to design/afps-tracker/flow-tree-afps-tracker.yaml after approval.
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: 6Approval Gates
Gate 1: Approve Canonical Flow Map Write
Gate 2: Approve Interview Log Write
Gate 3: Approve Flow-Tree Manifest Initialization
Compile Responses
Answer the gates above, then compile and paste the YAML back to the agent. Approval writes the canonical artifacts; revision or clarification keeps this page in review.
No response compiled yet.