UX Variations: Orient To Product Portfolio

Quick-Scan Overview Full Intermediate Spec

design/afps-tracker/ux-variations-uf-orient-portfolio/quick-scan-overview.md

skill: ux-variations
topic: uf-orient-portfolio
product_path: research/afps-tracker
parent_flow_branch: uf-orient-portfolio
variation_id: quick-scan-overview
status: intermediate
source_command: "$ux-variations uf-orient-portfolio"
brief: design/afps-tracker/_working/ux-variations-uf-orient-portfolio-brief.md
flow_tree: design/afps-tracker/flow-tree-afps-tracker.yaml
user_flow: design/afps-tracker/user-flow-afps-tracker.md
domain_model: design/afps-tracker/domain-model-afps-tracker.md
model_tree: design/afps-tracker/model-tree-afps-tracker.yaml

Quick-Scan Overview

Design Thesis

Quick-Scan Overview optimizes the orientation branch for the fastest credible first read of an AFPS portfolio. The operator should open AFPS Tracker and immediately understand how many paths exist, which paths are active or parallel, whether the source state is clean, warning, or blocked, and which path can be selected next.

The variation deliberately keeps diagnostics and provenance visible but secondary. It assumes a returning operator who mostly trusts the repository state and needs to rebuild context quickly after compaction, session restart, or handoff.

Target User Fit

Best fit: AFPS power user or AI workflow operator returning to a familiar repo where source files usually parse cleanly.

Usage context:

• The operator wants a short portfolio read before choosing a product path.
• The repo may contain multiple active or parallel research paths.
• The user wants warning visibility without being forced into diagnostic triage first.
• The user is likely to move next into `uf-verify-selected-path` after selecting a row.

Poor fit:

• The repo is known to be malformed, stale, or contradictory.
• The operator's first question is source trust rather than portfolio orientation.
• The session goal is to explain inactive or promoted boundaries in depth.

Parent Flow And Branch Relationship

Parent user-flow branch: `uf-orient-portfolio`.

Branch boundary: open tracker, scan portfolio, understand active and parallel paths, and select a path for deeper inspection. This variation must not absorb selected-path verification, evidence/provenance inspection, diagnostics recovery, export, or boundary explanation flows.

Logical substrate preserved:

• `RepositoryContext` triggers and displays the portfolio read-through.
• `PortfolioSnapshot` provides grouped path state, source health, parser confidence, source confidence, active refs, excluded refs, and unresolved refs.
• `PortfolioPathRef` preserves active, excluded, unresolved, inactive, and boundary refs.
• `ProductPath` rows expose source status, stage, next skill, trust level, handoff eligibility, and boundary kind.
• `DiagnosticIssue` remains visible at the narrowest affected scope and suppresses unsafe clean actions.

Page And Flow Changes

This variation makes `Portfolio Overview` the dominant first surface. It compresses source health, path counts, active paths, and selection controls into one scan-first page.

Primary flow:

1. Open AFPS Tracker on an existing repository.
2. See a portfolio summary strip with scan state, path counts, active refs, warnings, and blocked issues.
3. Scan active and parallel path rows grouped by status.
4. Select the path that looks like the right next context.
5. Continue to selected-path verification with the selected path ID and visible warnings preserved.

Secondary paths:

• If there is exactly one safe active path, the page may preselect it visually but still labels the selection as source-derived, not an irreversible decision.
• If warnings exist, the summary strip keeps a persistent warning count and row-level badges visible.
• If blocking diagnostics exist, selection can still inspect rows, but clean next-command or handoff affordances are suppressed.
• If no paths exist, the page shows checked source paths and an empty/no-AFPS state instead of inventing guidance.

Progression Model

Progression is scan-first and row-selection driven.

The user advances by reading the top summary and selecting a product path row. The UI does not require a wizard, diagnostic acknowledgement, evidence drilldown, or command search before selection. Warnings and trust limits ride along as badges, banners, and disabled-action reasons.

How this differs from sibling concepts:

• Unlike Trust-First Source Health, the user sees source health as a compact status strip, not the first full workspace.
• Unlike Diagnostics-First Recovery, clean or warning portfolios remain immediately selectable.
• Unlike Portfolio-Map Grouping, status grouping is compact and list-like rather than spatially expansive.
• Unlike Command/Resume-First Orientation, the first object is portfolio selection, not a provisional next-command answer.

Completion criteria:

• The user can name the active and parallel paths.
• The user can tell whether the portfolio is clean, warning, partial, or blocked.
• The user can select one path for the next verification branch.
• The user has not been misled into treating inactive, promoted, archived, unresolved, or contradicted paths as normal active routes.

Onboarding And Activation Model

First-run onboarding is minimal and contextual.

Initial frame:

• Short scan status while `ScanPortfolio` runs.
• Empty state that names the source checked when no AFPS state exists.
• One inline explanation in the summary strip when warnings exist: the overview is still usable, but handoff and source-backed claims depend on warning severity.

Activation moment:

The operator reaches first value when the summary strip and grouped path rows show active and parallel paths clearly enough to choose a path without reading raw files.

The page should avoid tutorial copy. It should use structure, labels, and badges to make the workflow obvious.

Typical Workflow Sequence

1. Repository scan begins.
2. Portfolio summary strip appears with source health and path counts.
3. Active paths are shown first, followed by parallel or inactive context groups.
4. Each path row shows label, ID, status, pipeline stage, next skill, last touched, trust level, and warning count.
5. The operator selects a path row.
6. A compact selection preview appears inline or in a right-side detail summary, showing selected path status and any blocking caveats.
7. The primary action moves to selected-path verification.
8. If the operator needs evidence, provenance, diagnostics, or boundary explanation, secondary links route to sibling branches instead of expanding the orientation flow.

Sharing, Collaboration, And Permissions Model

This variation assumes solo evaluator use by default. It does not introduce collaboration, account roles, invitations, comments, or permissions.

Share-like behavior is limited to later handoff concerns:

• Copy or export controls are not primary in this branch.
• A disabled or provisional handoff preview may appear only when it preserves warnings and does not replace `uf-handoff-resume`.
• Reviewer-facing explanation belongs to later verification, provenance, or handoff flows.

Permission-denied source reads are treated as diagnostics. The page names inaccessible files and keeps unaffected source-backed rows visible.

Return-Use And Notification Model

Return use is passive and source-native.

Re-entry triggers:

• Opening the repo after context loss.
• Returning from an alignment page or progress manifest.
• Starting a new Codex or Claude session and needing portfolio context.
• Reviewing whether multiple active paths still exist.

The page does not use notifications. It should show scan freshness, source timestamps when available, and `last_touched` values so a returning user can judge whether the view is current.

Failure Recovery And Abandoned-Workflow Behavior

Recovery remains visible but compact.

Failure states:

• No progress manifest: show no-manifest empty state with checked path.
• Malformed manifest: show blocking summary and suppress clean route actions.
• Unresolved active ref: show unresolved ref row or warning item instead of dropping it.
• Missing scoped path: keep manifest-backed row but mark scoped support unavailable.
• Permission denied: label affected path and keep partial map visible.
• Contradictory source status: show contradiction and suppress clean next action.
• Promoted or inactive path selected: show boundary label and route to boundary explanation instead of normal active continuation.

Abandoned workflow:

If the user leaves after scanning but before selecting, no state write-back occurs. On return, the tracker rescans canonical files and labels scan freshness. If a prior selected path can be retained locally by the eventual implementation, it must be visually subordinate to the new scan state.

Navigation Model

Navigation is shallow and overview-centered.

Primary navigation:

• Portfolio Overview as the landing surface.
• Row selection advances to Product-Path Detail or selected-path verification.

Secondary navigation:

• Source health link opens diagnostics.
• Warning badges open diagnostics scoped to row or portfolio.
• Evidence or provenance links route to source/provenance inspection only after a path is selected.
• Boundary labels route to inactive/promoted boundary explanation.

No global side navigation is required for this variation. If a shell exists later, the overview should still be the first meaningful screen.

Screen-By-Screen Layout

Screen 1: Loading / Scan

Purpose: communicate that the tracker is reading repo-local source files.

Regions:

• Header: repository label and scan status.
• Summary skeleton: source health, path counts, active refs.
• Row skeleton: grouped path rows.
• Diagnostics placeholder: visible if scan already detects source access issues.

Key behavior:

• Loading should not imply network activity.
• Prior loaded state, if implemented later, must be labelled as prior state until the new scan completes.

Screen 2: Portfolio Overview

Purpose: let the operator orient and select.

Regions:

• Header: product name, repository context, scan freshness.
• Source-health strip: clean/warning/blocked status, parser confidence, source confidence, unresolved refs, blocking issue count.
• Portfolio summary: active count, parallel count, inactive/context count, promoted or out-of-scope count when present.
• Grouped path list: active first, then parallel/context groups.
• Row affordances: select path, inspect warnings, show suppressed-route reason.

Row content:

• Path label and ID.
• Status and boundary label.
• Pipeline stage.
• Next skill when safe or suppression reason when unsafe.
• Scope path.
• Last touched.
• Trust level.
• Warning/diagnostic count.

Screen 3: Selected Row Preview

Purpose: confirm selection without turning orientation into deep verification.

Regions:

• Selected row highlight.
• Compact preview panel or expanded inline row.
• Primary action: continue to verification.
• Secondary actions: inspect diagnostics, evidence, provenance, or boundary explanation.

Key behavior:

• Primary action is enabled for selectable active/warning paths but must carry warning context forward.
• Clean next-command copy is not offered here when trust-dependent handoff remains unverified.
• Inactive, promoted, archived, deferred, unresolved, or contradicted paths route to explanation/recovery rather than normal active verification.

Screen 4: Empty / No-AFPS State

Purpose: avoid fabricated guidance.

Regions:

• Source checked.
• Explanation that no AFPS product paths were found.
• Diagnostic details if relevant.
• Optional next source to inspect manually, if source evidence supports it.

Screen 5: Blocking Diagnostic Summary

Purpose: preserve orientation while preventing false confidence.

Regions:

• Blocking issue banner.
• Affected source files and path refs.
• Rows that remain readable.
• Disabled or suppressed actions with explicit reasons.

Key Components And Controls

Components:

• Repository scan header.
• Source-health strip.
• Portfolio count summary.
• Grouped path list.
• Product-path row.
• Trust badge.
• Diagnostic badge.
• Boundary badge.
• Selected-row preview.
• Empty state.
• Blocking diagnostic banner.

Controls:

• Select path row.
• Filter or toggle group visibility by status.
• Open source health.
• Open row diagnostics.
• Continue to verify selected path.
• Open boundary explanation when selection is inactive or promoted.

Avoid:

• Primary copy-next-command button in this branch.
• Hidden warnings behind hover-only controls.
• Drag-and-drop, kanban movement, or write-back controls.
• Account, invitation, or permission controls.

Button And Link Behavior

Primary button: `Continue to verify path`.

Enabled when:

• A product path is selected.
• The path is active or warning-level and not blocked by source contradiction, unreadable required source, promoted boundary, or out-of-scope boundary.

Disabled or suppressed when:

• No path is selected.
• The path is inactive, promoted, archived, deferred, revisit-candidate, unresolved, contradicted, unsupported, or blocked.
• The required selected-path source support is unreadable or malformed.

Secondary links:

• `Inspect source health`: opens diagnostics for portfolio-level issues.
• `Review warnings`: opens diagnostics scoped to selected row.
• `Explain boundary`: routes inactive/promoted/out-of-scope rows to boundary explanation.
• `Inspect evidence` and `Inspect provenance`: available only when a selected path has relevant refs; otherwise hidden or visibly unavailable with reason.

Links must preserve source paths, warning IDs, selected path ID, trust level, parser confidence, and source confidence in the downstream context.

Spatial Density, Sizing, And Hierarchy

Density: compact to comfortable.

Hierarchy:

1. Source-health strip and portfolio counts.
2. Active path group.
3. Parallel/context path groups.
4. Row-level warnings and boundary labels.
5. Secondary diagnostics and source actions.

List rows should support fast scanning with predictable columns or column-like regions. Warning and boundary labels must be visible without expanding the row.

The visual feel should be restrained and operational, closer to a source-aware dashboard than a marketing overview. Cards may be used for repeated path rows, but avoid nested cards and decorative framing.

Responsive Behavior

Desktop:

• Summary strip and counts span the top.
• Grouped path list occupies the main region.
• Selected-row preview may appear as an inline expansion or right-side detail panel.

Tablet:

• Summary strip wraps into two rows.
• Path rows retain key fields: label, status, stage, trust, warning count, selected action.
• Secondary metadata can collapse into an expanded row.

Mobile:

• Summary strip becomes stacked status blocks.
• Path rows become compact list items with visible badges.
• Filters collapse into simple group toggles.
• Selection preview appears below the selected row.
• No horizontal table should be required for first value.

Visual Tone

Tone: calm, source-aware, utilitarian, and fast.

The page should communicate confidence without hiding risk. Clean source state can feel light and efficient, but warning and blocked states need enough contrast to prevent false reassurance.

Avoid heavy onboarding illustrations, large hero sections, decorative gradients, or single-hue styling. The UI should feel like a reliable local operator surface.

Strengths

• Fastest path to first value for clean or mostly clean repositories.
• Keeps the orientation branch tightly bounded.
• Reduces cognitive load for returning operators who just need the portfolio map.
• Minimizes implementation complexity before UI interview.
• Preserves warning visibility while keeping diagnostics secondary.

Risks And Failure Modes

• Warning badges may be too subtle if visual priority is not handled carefully.
• Users with low trust in the repo may feel forced to select before understanding source health.
• A compact list can under-explain inactive, promoted, or unresolved branch boundaries.
• A selected-row preview could accidentally absorb too much selected-path verification.
• If a provisional handoff preview is included, it may blur into `uf-handoff-resume`.

Mitigations:

• Keep source-health strip persistent and plain-language.
• Make blocking diagnostics visually interrupt the quick path.
• Route boundary and provenance depth to sibling branches instead of expanding inline.
• Do not expose clean copy-next-command behavior in this branch.

Implementation Complexity

Estimated complexity: low to medium.

Reasons:

• Uses one dominant overview surface and optional selected-row preview.
• Depends on existing read models from the domain model.
• Does not require collaboration, write-back, complex navigation, or full diagnostics workspace.
• Requires careful warning and disabled-action rules, but fewer unique screens than recovery-first or portfolio-map concepts.

Implementation-sensitive areas:

• Compact representation of trust envelopes.
• Row grouping and state filters.
• Disabled-action reasons.
• Clean handling of unresolved active refs and partial source data.

What UI Review Should Validate First

UI review should validate whether the page delivers orientation without burying source trust.

Priority validation questions:

• Can the operator identify active and parallel paths within a few seconds?
• Are warning, partial, blocked, unresolved, inactive, and promoted states visible before selection?
• Does the selected-row preview stay lightweight enough to avoid replacing selected-path verification?
• Does the primary action clearly route to verification rather than promising a final next command?
• Does the view remain useful when there are two active paths, one unresolved active ref, and one promoted parallel path?

User Signal For UI Interview Readiness

This branch is ready for `$ui-interview` if a reviewer agrees that Quick-Scan should be the baseline orientation candidate: fastest credible first read, source warnings visible in the overview, row selection clear, and no unsafe next-command or handoff behavior leaking into the activation branch.

Strong positive signal:

• The reviewer can choose a path and explain warning state from the overview alone.
• The reviewer does not need raw file reading for first value.
• The reviewer trusts that unsafe states are blocked or routed elsewhere.

Negative signal:

• The reviewer asks to inspect source health before understanding the path list.
• Warning/boundary states feel secondary or easy to miss.
• The layout feels too generic to explain AFPS-specific branch state.

Future Experiment Target

If this variation later receives UI approval, a future experiment route could be named `/experiments/quick-scan-overview`. Default progression-mode rules still apply: no prototype buildout or route implementation should be written from this UX variation alone before an approved `$ui-interview` branch exists.

Trust-First Source Health Full Intermediate Spec

design/afps-tracker/ux-variations-uf-orient-portfolio/trust-first-source-health.md

skill: ux-variations
topic: uf-orient-portfolio
product_path: research/afps-tracker
parent_flow_branch: uf-orient-portfolio
variation_id: trust-first-source-health
status: intermediate
source_command: "$ux-variations uf-orient-portfolio"
brief: design/afps-tracker/_working/ux-variations-uf-orient-portfolio-brief.md
flow_tree: design/afps-tracker/flow-tree-afps-tracker.yaml
user_flow: design/afps-tracker/user-flow-afps-tracker.md
domain_model: design/afps-tracker/domain-model-afps-tracker.md
model_tree: design/afps-tracker/model-tree-afps-tracker.yaml

Trust-First Source Health

Design Thesis

Trust-First Source Health makes source trust the first object of orientation. The operator should open AFPS Tracker and immediately understand whether the repo-local portfolio read is fresh, source-backed, partial, inferred, warning-level, or blocked before committing attention to a product path.

The variation treats path selection as a consequence of source-health interpretation. It assumes the operator may be returning after a long gap, repo churn, parser warnings, context loss, or previous ambiguity, and therefore needs confidence in the read model before they trust the portfolio list.

Target User Fit

Best fit: AFPS operator or AI workflow maintainer who needs to re-establish trust before resuming a product path.

Usage context:

• The repo has changed since the last trusted read-through.
• Previous sessions raised parse warnings, unresolved refs, or provenance gaps.
• The operator needs to know which displayed path facts are source-backed versus inferred.
• The user is likely to move next into `uf-verify-selected-path`, but only after the overview explains source quality.

Poor fit:

• The repo is known clean and the operator only wants the fastest possible path selection.
• The user's first question is command continuity rather than trust state.
• The session goal is full diagnostic recovery or source repair triage.

Parent Flow And Branch Relationship

Parent user-flow branch: `uf-orient-portfolio`.

Branch boundary: open tracker, scan portfolio, understand active and parallel paths, and select a path for deeper inspection. This variation changes the order of attention inside orientation: source health first, path list second. It must not absorb full diagnostic recovery, evidence/provenance inspection, selected-path verification, handoff/export, or inactive/promoted boundary explanation.

Logical substrate preserved:

• `RepositoryContext` owns scan status, source health, scan freshness, warnings, and portfolio-level diagnostics.
• `PortfolioSnapshot` exposes snapshot state, active/excluded/unresolved refs, parser confidence, source confidence, and path groups.
• `PortfolioPathRef` preserves active, excluded, unresolved, inactive, and boundary refs even when the ref does not resolve to a usable `ProductPath`.
• `ProductPath` rows carry trust level, source status, parser/source confidence, stage, next skill, handoff eligibility, boundary kind, and diagnostics.
• `DiagnosticIssue` attaches at the narrowest affected source, claim, path, portfolio, or handoff level.
• Every trust-bearing response carries `trust_level`, `parser_confidence`, `source_confidence`, `warnings[]`, and `diagnostic_refs[]`.

Page And Flow Changes

This variation makes `Source Health` the dominant first surface inside the portfolio overview. The path list remains visible, but the first scan object is a trust envelope that explains what the tracker read, what it could not read, and which path groups inherit caveats.

Primary flow:

1. Open AFPS Tracker on an existing repository.
2. See a source-health console with scan freshness, manifest state, parser confidence, source confidence, warning counts, blocked issues, and unresolved refs.
3. Review how the health envelope affects active, parallel, inactive, promoted, and unresolved path groups.
4. Select a product path with trust context already attached.
5. Continue to selected-path verification with trust envelope, warning IDs, and diagnostic refs preserved.

Secondary paths:

• If the portfolio is clean, the health console collapses into a compact but still visible source-backed summary.
• If warning-level issues exist, the affected group and path rows inherit visible caveats before selection.
• If blocking diagnostics exist, path inspection remains possible but clean next-command or handoff affordances are suppressed.
• If unresolved active refs exist, the source-health console lists them before the path table so they cannot disappear into row-level noise.

Progression Model

Progression is trust-envelope-first and path-selection-second.

The user advances by reading the source-health summary, deciding whether the portfolio is sufficiently trustworthy for orientation, and then selecting a path row. The UI does not require the user to fix diagnostics before orientation, but it makes trust state impossible to miss.

How this differs from sibling concepts:

• Unlike Quick-Scan Overview, source health is not a strip above the list; it is the primary workspace that frames the list.
• Unlike Diagnostics-First Recovery, the page does not start as a triage queue or repair workflow; clean and warning portfolios remain oriented around selection.
• Unlike Portfolio-Map Grouping, path state is explained through trust envelopes rather than spatial lanes.
• Unlike Command/Resume-First Orientation, the first object is source confidence, not a provisional next-command answer.

Completion criteria:

• The user can say whether the portfolio read is clean, partial, warning-level, or blocked.
• The user can distinguish parser confidence from source confidence.
• The user can identify which active or parallel paths are safe to inspect and which carry caveats.
• The user can select a path without mistaking inactive, promoted, unresolved, contradicted, or unsupported state for clean active work.

Onboarding And Activation Model

First-run onboarding is embedded in the source-health console.

Initial frame:

• Scan status names the repo-local sources being checked.
• Health cards explain manifest parse state, source confidence, parser confidence, unresolved refs, and blocking issue count.
• A short source-state legend can define clean, warning, partial, inferred, unsupported, contradicted, and blocked labels.

Activation moment:

The operator reaches first value when they trust the shape of the portfolio enough to choose what to inspect next, even if some source warnings remain unresolved.

The page should not teach AFPS from scratch. It should make the trust contract obvious through field labels, badges, warnings, and source refs.

Typical Workflow Sequence

1. Repository scan begins and displays source files being checked.
2. Source-health console loads first with scan freshness, manifest state, parser confidence, source confidence, unresolved refs, and issue severity.
3. A compact impact summary groups caveats by portfolio-level, path-level, source-level, and handoff-level impact.
4. Path groups appear below or beside the health console with trust badges inherited from the source envelope.
5. The operator expands or filters by trust state when necessary.
6. The operator selects a product path row.
7. A selected path trust summary confirms why selection is safe, warning-level, blocked, or boundary-routed.
8. The primary action moves to selected-path verification only when source state supports inspection; blocked or boundary states route to recovery or explanation branches.

Sharing, Collaboration, And Permissions Model

This variation assumes solo evaluator use and does not introduce accounts, invitations, comments, collaborative review, or role permissions.

Permission boundaries are source-health inputs:

• Permission-denied files appear in the health console before path selection.
• Unaffected source-backed rows remain visible when partial data is available.
• Trust-dependent handoff or next-command controls remain suppressed when inaccessible sources support selected state.

Share-like behavior is limited to later handoff concerns. A source-health summary may preview what caveats would need to travel with a future handoff, but copy/export controls are not primary in this orientation branch.

Return-Use And Notification Model

Return use is trust-refresh oriented.

Re-entry triggers:

• Opening AFPS Tracker after a long gap.
• Returning from a different agent session, compaction, or handoff.
• Seeing that product paths changed or source files were amended.
• Needing to verify whether old warnings still apply.

The page does not use notifications. Instead, it emphasizes scan freshness, last-read time when available, current source paths, and whether cached or prior scan state is being replaced by a fresh repo-local read.

Failure Recovery And Abandoned-Workflow Behavior

Recovery remains visible and source-scoped, but not full triage.

Failure states:

• Missing progress manifest: health console shows no-manifest state and checked path before the empty portfolio area.
• Malformed manifest: parser confidence drops to blocked; clean route actions are suppressed.
• Unresolved active ref: unresolved refs appear in the health console and in path-group impact summaries.
• Missing scoped path: path remains represented as manifest-backed but scoped support is unavailable.
• Permission denied: affected source path is named and affected rows inherit the caveat.
• Contradictory status: source confidence drops to contradicted for affected claims or paths; clean next action is suppressed.
• Promoted or inactive path selected: boundary kind is shown as a trust/boundary state, not a normal active route.

Abandoned workflow:

If the user leaves after reviewing source health but before selecting, no state write-back occurs. On return, the tracker rescans canonical files and labels scan freshness. Any remembered selection must be subordinate to the newly read source-health envelope.

Navigation Model

Navigation is shallow, but trust-centered.

Primary navigation:

• Portfolio Overview opens with Source Health in primary focus.
• Path selection advances to selected-path verification only after trust context is visible.

Secondary navigation:

• `Open diagnostics` routes to diagnostics when a warning or blocked issue needs recovery.
• `Inspect affected source` routes to evidence/source inspection after path or source selection.
• `Explain boundary` routes inactive, promoted, archived, deferred, revisit-candidate, unresolved, or out-of-scope paths to boundary explanation.
• `Review provenance` is available for selected paths with provenance refs, but is not required before basic orientation.

A global side nav is optional. If present later, Source Health should remain part of the overview surface rather than becoming a separate administration page.

Screen-By-Screen Layout

Screen 1: Loading / Source Scan

Purpose: communicate that the tracker is reading repo-local AFPS artifacts and computing trust state.

Regions:

• Header: repository label, scan status, and source files being checked.
• Health skeleton: manifest state, parser confidence, source confidence, unresolved refs, issue severity.
• Path group skeleton: active and parallel groups held until source envelope resolves.
• Warning placeholder: appears as soon as source access or parse issues are detected.

Key behavior:

• Loading should name local source reads, not imply network activity.
• Prior scan state, if shown, must be labelled as prior state until the current scan completes.

Screen 2: Source Health Console

Purpose: make trust state legible before path selection.

Regions:

• Header: product name, repository context, scan freshness.
• Trust envelope summary: clean/warning/partial/blocked state, parser confidence, source confidence, diagnostic count.
• Source inventory: progress manifest, scoped research directories, alignment/provenance refs when available, archive/working refs when relevant.
• Impact summary: portfolio-level, path-level, source-level, and handoff-level impacts.
• Unresolved refs list: active refs, evidence refs, provenance refs, and source refs that could not be resolved.

Key behavior:

• Parser confidence and source confidence are displayed separately.
• Health cards name affected source paths or explain when no source path exists.
• Blocking issues suppress clean route actions globally until scoped by the next flow.

Screen 3: Trust-Annotated Portfolio

Purpose: let the operator select a path with trust context already attached.

Regions:

• Trust filters: clean, warning, partial, blocked, inferred, boundary.
• Grouped path list: active first, then parallel/context groups.
• Row trust summary: trust level, source status, parser confidence, source confidence, warning count, boundary kind.
• Source impact badges: shows whether a row inherits portfolio-level caveats or has path-specific issues.

Row content:

• Path label and ID.
• Status and boundary label.
• Pipeline stage.
• Next skill when safe, or suppression reason when unsafe.
• Scope path.
• Last touched.
• Trust level.
• Parser/source confidence pair.
• Warning/diagnostic count.

Screen 4: Selected Path Trust Summary

Purpose: confirm selection through trust context without replacing selected-path verification.

Regions:

• Selected row highlight.
• Trust envelope recap for the selected path.
• Affected sources and diagnostics.
• Primary action: continue to verification.
• Secondary actions: open diagnostics, inspect affected source, review provenance, explain boundary.

Key behavior:

• Primary verification action is enabled for selectable active or warning-level paths when source state allows inspection.
• Clean next-command copy is not offered in this branch.
• Blocked, promoted, inactive, archived, deferred, unresolved, contradicted, unsupported, or out-of-scope paths route to recovery or boundary explanation instead of normal active verification.

Screen 5: Empty / No-AFPS Or No-Trust State

Purpose: avoid fabricated portfolio guidance.

Regions:

• Source checked.
• Manifest state.
• Explanation that no AFPS product paths or no trustworthy path records were found.
• Diagnostic details if source evidence supports them.

Screen 6: Blocking Health Summary

Purpose: preserve orientation while making unsafe trust state impossible to miss.

Regions:

• Blocking issue banner.
• Affected source files and path refs.
• What remains readable.
• Which actions are suppressed and why.

Key Components And Controls

Components:

• Repository scan header.
• Source-health console.
• Trust envelope summary.
• Parser/source confidence pair.
• Source inventory list.
• Unresolved refs list.
• Impact summary by affected level.
• Trust-filtered path groups.
• Product-path row with inherited caveats.
• Selected path trust summary.
• Blocking health banner.
• Empty/no-trust state.

Controls:

• Filter paths by trust state.
• Select path row.
• Open diagnostics for affected issue.
• Inspect affected source.
• Continue to verify selected path.
• Explain boundary for inactive/promoted/out-of-scope rows.

Avoid:

• Primary copy-next-command button.
• Hidden or hover-only warnings.
• Repair/edit/write-back controls.
• Full diagnostic triage queues that belong to `diagnostics-first-recovery`.
• Visual patterns that imply source health is optional metadata.

Button And Link Behavior

Primary button: `Continue to verify path`.

Enabled when:

• A product path is selected.
• The path is active or warning-level.
• The selected path is not blocked by source contradiction, unreadable required source, malformed required source, promoted boundary, or out-of-scope boundary.
• Warning context and diagnostic refs can be carried forward.

Disabled or suppressed when:

• No path is selected.
• Source-health state is portfolio-blocked and the selected path cannot be safely inspected.
• The path is inactive, promoted, archived, deferred, revisit-candidate, unresolved, contradicted, unsupported, out-of-scope, or blocked.
• Required source support for selected-path verification is missing, unreadable, or malformed.

Secondary links:

• `Open diagnostics`: opens diagnostics scoped to the source-health issue.
• `Inspect affected source`: routes to source/provenance inspection for the selected path or source.
• `Show unresolved refs`: focuses unresolved active/evidence/provenance refs.
• `Explain boundary`: routes inactive, promoted, archived, deferred, revisit-candidate, unresolved, or out-of-scope rows to boundary explanation.

Links must preserve source paths, issue IDs, selected path ID, trust level, parser confidence, source confidence, source status, warning IDs, and diagnostic refs.

Spatial Density, Sizing, And Hierarchy

Density: data-dense but readable.

Hierarchy:

1. Source-health state and scan freshness.
2. Parser confidence and source confidence.
3. Unresolved refs and blocking/warning impact.
4. Trust-annotated active path group.
5. Parallel and context groups.
6. Secondary source/provenance/deeper diagnostic actions.

The layout should support fast comparison of trust fields without forcing a full table for first value. Health cards or compact panels can be used for the top console, with rows below using predictable columns or column-like regions.

The visual feel should be operational and evidence-aware. It can be denser than Quick-Scan, but it should still feel like an orientation surface rather than a log viewer.

Responsive Behavior

Desktop:

• Source-health console occupies the top or left primary region.
• Trust-annotated path list occupies the main region.
• Selected path trust summary may appear as a right-side panel or inline expansion.

Tablet:

• Health console stacks into two rows: trust state first, source inventory second.
• Path rows retain label, status, trust level, confidence pair, warning count, and selected action.
• Impact summary can collapse into expandable groups.

Mobile:

• Health state becomes the first stacked block.
• Parser/source confidence pair remains visible before path rows.
• Path rows become compact list items with trust and warning badges.
• Source inventory and unresolved refs collapse behind plain expandable sections.
• No horizontal table should be required for first value.

Visual Tone

Tone: cautious, precise, source-native, and calm.

The page should communicate that the tracker earns trust by exposing source quality. Clean source state may feel efficient, but warning, partial, unsupported, contradicted, and blocked states need enough visual weight to prevent false reassurance.

Avoid hero treatment, decorative gradients, vague "health score" theatrics, or a single aggregate score that hides parser/source differences. Use direct labels and source-backed details.

Strengths

• Strongest fit for operators who do not yet trust repo state.
• Makes parser confidence, source confidence, unresolved refs, and warning impact visible before path selection.
• Reduces risk of false confidence after repo churn, context loss, or stale artifacts.
• Preserves the read-first model without forcing diagnostic repair.
• Provides a clear contrast against Quick-Scan for later UI review.

Risks And Failure Modes

• The first screen may feel slower than necessary for clean repositories.
• Dense trust details can overwhelm a user who only needs path selection.
• If health panels become too diagnostic-heavy, the variant can drift into `diagnostics-first-recovery`.
• A single source-health summary could hide row-specific caveats if inherited warnings are not attached to rows.
• Overemphasizing source health could make active path selection feel secondary.

Mitigations:

• Collapse clean health into a compact summary while preserving source confidence labels.
• Keep path rows visible on the same surface as source health.
• Route repair and deep triage to diagnostics instead of building it inline.
• Attach inherited caveats and row-specific warnings directly to affected rows.
• Keep the primary action framed as verification, not final handoff.

Implementation Complexity

Estimated complexity: medium.

Reasons:

• Requires richer trust-envelope presentation than Quick-Scan.
• Needs careful mapping from portfolio/source diagnostics to group and row impacts.
• Still uses the same core read models and does not require write-back, collaboration, or full recovery workflow.
• Requires responsive handling of health panels, filters, and row caveats.

Implementation-sensitive areas:

• Separate display of parser confidence and source confidence.
• Inherited caveat propagation from portfolio/source level to path rows.
• Unresolved refs handling without hiding selectable source-backed rows.
• Disabled-action reasons under blocked, promoted, inactive, contradicted, unsupported, or out-of-scope states.

What UI Review Should Validate First

UI review should validate whether trust-first orientation improves confidence without burying path selection.

Priority validation questions:

• Can the operator immediately tell whether the portfolio read is clean, warning, partial, or blocked?
• Are parser confidence and source confidence understandable as separate signals?
• Can the operator still identify active and parallel paths quickly after reading source health?
• Do row-level caveats clearly show which warnings are inherited versus path-specific?
• Does the page avoid becoming a diagnostics repair workflow?
• Does the primary action clearly route to verification rather than promising a clean next command?

User Signal For UI Interview Readiness

This branch is ready for `$ui-interview` if a reviewer agrees that AFPS Tracker should lead orientation with source trust: the user needs confidence in manifest freshness, parser confidence, source confidence, unresolved refs, and warning impact before deciding which path to inspect.

Strong positive signal:

• The reviewer can explain why a path is safe, warning-level, partial, or blocked before selecting it.
• The reviewer sees source-health caveats without reading raw files.
• The reviewer still understands which active or parallel path to inspect next.

Negative signal:

• The reviewer says the source-health console slows down normal clean-repo use too much.
• The reviewer still needs raw files to understand trust state.
• The page feels like a diagnostics queue rather than orientation.
• Path selection is visually subordinate enough that first value becomes unclear.

Future Experiment Target

If this variation later receives UI approval, a future experiment route could be named `/experiments/trust-first-source-health`. Default progression-mode rules still apply: no prototype buildout or route implementation should be written from this UX variation alone before an approved `$ui-interview` branch exists.

Diagnostics-First Recovery Full Intermediate Spec

design/afps-tracker/ux-variations-uf-orient-portfolio/diagnostics-first-recovery.md

skill: ux-variations
topic: uf-orient-portfolio
product_path: research/afps-tracker
parent_flow_branch: uf-orient-portfolio
variation_id: diagnostics-first-recovery
status: intermediate
source_command: "$ux-variations uf-orient-portfolio"
brief: design/afps-tracker/_working/ux-variations-uf-orient-portfolio-brief.md
flow_tree: design/afps-tracker/flow-tree-afps-tracker.yaml
user_flow: design/afps-tracker/user-flow-afps-tracker.md
domain_model: design/afps-tracker/domain-model-afps-tracker.md
model_tree: design/afps-tracker/model-tree-afps-tracker.yaml

Diagnostics-First Recovery

Design Thesis

Diagnostics-First Recovery treats recovery from stale, missing, contradictory, unreadable, or unresolved state as the primary orientation job. The operator should open AFPS Tracker and immediately understand what remains usable, what is warning-level, what is blocked, and which product paths can be safely inspected before they select work.

The variation is intentionally safety-forward. It assumes the operator may be arriving after a failed scan, malformed manifest, missing scoped research path, unresolved active ref, permission problem, or contradictory source state. The first object of attention is not a clean portfolio list or general source-health confidence; it is an actionable recovery triage that preserves orientation while preventing false confidence.

Target User Fit

Best fit: AFPS operator or AI workflow maintainer returning to a repo after suspected source damage, stale artifacts, branch-state contradiction, incomplete handoff, or a prior blocked tracker read.

Usage context:

• The repo may contain malformed YAML, missing paths, unresolved refs, or unreadable source files.
• The user needs to know what is still usable without treating warnings as clean state.
• The operator wants a path selection only after blocked and warning states are visible.
• The likely next branch may be selected-path verification for usable paths or diagnostics recovery for blocked state.

Poor fit:

• The repo is known clean and the operator wants the fastest possible scan.
• The user wants a broad explanation of branch-state topology rather than recovery priority.
• The session goal is a final handoff or next-command copy.

Parent Flow And Branch Relationship

Parent user-flow branch: `uf-orient-portfolio`.

Branch boundary: open tracker, scan portfolio, understand active and parallel paths, and select a path for deeper inspection. This variation changes orientation by leading with recovery classification and safe-selection state. It must not absorb the full sibling `uf-recover-diagnostics` branch, where the operator reviews diagnostics deeply and routes to source verification or manual correction.

Logical substrate preserved:

• `RepositoryContext` owns scan state, source health, warnings, and portfolio-level diagnostics.
• `PortfolioSnapshot` exposes snapshot state, active and excluded refs, unresolved refs, parser confidence, source confidence, and path groups.
• `PortfolioPathRef` preserves unresolved, inactive, boundary, and excluded refs even when no usable `ProductPath` resolves.
• `ProductPath` rows expose path state, source status, trust level, next skill, handoff eligibility, boundary kind, and diagnostics.
• `DiagnosticIssue` attaches at the narrowest affected source, claim, path, portfolio, or handoff level.
• Diagnostic severity and affected level remain separate dimensions, so a source-level warning does not automatically block unrelated path-level orientation.

Page And Flow Changes

This variation makes `Recovery Triage` the dominant first surface inside the portfolio overview. The path list remains present, but it is organized around usability: usable now, warning-level, blocked, unresolved, and boundary-routed.

Primary flow:

1. Open AFPS Tracker on an existing repository.
2. See a recovery triage header with blocking issue count, warning count, unresolved refs, affected scope, and what remains usable.
3. Review diagnostic clusters by severity and affected level.
4. Select a product path from the safe or warning-level groups, or route a blocked group to diagnostics recovery.
5. Continue to selected-path verification only when the selected path can be inspected safely, carrying warnings and diagnostic refs forward.

Secondary paths:

• If no diagnostics exist, the page collapses recovery triage into a compact clean-state summary and exposes the path list quickly.
• If warning-level diagnostics exist, the page keeps path selection available while attaching caveats to affected rows.
• If blocking diagnostics exist, the page names the blocked action and the affected source, while leaving unaffected rows usable when possible.
• If unresolved active refs exist, they appear as first-class recovery items rather than disappearing from the portfolio.

Progression Model

Progression is recovery-triage-first and safe-selection-second.

The user advances by understanding diagnostic severity, affected scope, and remaining usable path groups before selecting a path or opening a recovery route. The UI does not demand that every issue be fixed before orientation, but it requires the user to see which parts of the portfolio are unsafe.

How this differs from sibling concepts:

• Unlike Quick-Scan Overview, diagnostics are not compact badges; they define the page structure.
• Unlike Trust-First Source Health, the first object is not confidence interpretation in general; it is recovery triage with severity, affected scope, and blocked action reasons.
• Unlike Portfolio-Map Grouping, branch state is organized by recovery usability rather than spatial portfolio topology.
• Unlike Command/Resume-First Orientation, the first object is not a provisional next command; unsafe command output is explicitly suppressed until recovery state allows it.

Completion criteria:

• The user can distinguish usable, warning-level, blocked, unresolved, inactive, promoted, and out-of-scope path states.
• The user can identify the source or path affected by a blocking diagnostic.
• The user can select a safe or warning-level path for verification, or route a blocked issue to diagnostics recovery.
• The UI does not imply that unresolved, contradicted, malformed, inactive, or promoted state is normal active work.

Onboarding And Activation Model

First-run onboarding is framed as recovery orientation.

Initial frame:

• Scan status names local source files being checked.
• Triage header explains whether the portfolio is clean, warning-level, partial, or blocked.
• A short severity legend can define usable, warning, blocked, unresolved, and boundary-routed.
• Affected-scope chips show whether issues are portfolio-level, source-level, path-level, claim-level, or handoff-level.

Activation moment:

The operator reaches first value when they know what parts of the portfolio can still be trusted enough to inspect and what is blocked or caveated before any selection.

The page should not teach diagnostics concepts as a tutorial. It should expose concrete source paths, affected refs, blocked actions, and safe next inspection choices.

Typical Workflow Sequence

1. Repository scan begins and displays source files being checked.
2. Recovery triage loads with counts for blocked, warning, unresolved, and usable items.
3. Diagnostic clusters group issues by severity and affected level.
4. The page shows `Usable now`, `Usable with warnings`, `Blocked`, `Unresolved refs`, and `Boundary/context` path groups.
5. The operator expands an issue cluster or selects a path row.
6. A selected-path recovery summary explains why the path is safe, warning-level, blocked, or boundary-routed.
7. The primary action either continues to selected-path verification or opens diagnostics recovery for the blocked issue.
8. Secondary links route to source/provenance inspection or boundary explanation without expanding the orientation branch into those sibling flows.

Sharing, Collaboration, And Permissions Model

This variation assumes solo evaluator use by default. It does not introduce accounts, invitations, collaborative triage, comments, roles, or permissions.

Permission and access problems are modeled as diagnostics:

• Permission-denied files appear in the recovery triage header and diagnostic clusters.
• Unaffected source-backed rows remain visible when partial orientation is possible.
• Trust-dependent handoff or next-command copy remains suppressed when inaccessible sources support the selected state.

Share-like behavior is limited to later handoff concerns. A blocked or warning state may preview the caveats a future handoff would need to carry, but copy/export controls are not primary in this orientation branch.

Return-Use And Notification Model

Return use is recovery-state refresh.

Re-entry triggers:

• Opening the tracker after a failed or partial prior scan.
• Returning after a session restart, compaction, or handoff that mentioned warnings.
• Reviewing whether previous unresolved refs, missing artifacts, or parse errors still block work.
• Checking whether active paths remain usable after repo changes.

The page does not use notifications. Instead, it emphasizes scan freshness, issue persistence, affected source paths, and whether previous blocked/warning state is still present after the current read.

Failure Recovery And Abandoned-Workflow Behavior

Recovery is central but bounded to orientation.

Failure states:

• Missing progress manifest: show no-manifest recovery state with checked path and no fabricated portfolio rows.
• Malformed manifest: show blocking parser issue, affected source, and suppressed clean route actions.
• Unresolved active ref: show unresolved ref as a recoverable portfolio item and prevent silent omission.
• Missing scoped path: keep manifest-backed path visible, mark scoped support unavailable, and route deeper checks to diagnostics/source inspection.
• Permission denied: name the inaccessible path and preserve unaffected readable rows.
• Contradictory source status: show contradictory values, affected claims or paths, and suppressed clean next action.
• Promoted or inactive path selected: show boundary kind and route to boundary explanation instead of normal active verification.

Abandoned workflow:

If the user leaves while triage is open, no state write-back occurs. On return, the tracker rescans canonical files and labels whether issues are current, resolved, or newly discovered. Any remembered filter or selected issue must be subordinate to the fresh scan result.

Navigation Model

Navigation is shallow but triage-centered.

Primary navigation:

• Portfolio Overview opens with Recovery Triage in primary focus.
• Safe or warning-level path selection advances to selected-path verification.
• Blocked issue selection routes to diagnostics recovery.

Secondary navigation:

• `Open diagnostics recovery` routes to the sibling `uf-recover-diagnostics` branch for deeper issue review.
• `Inspect affected source` routes to source/provenance inspection when a source path or claim exists.
• `Explain boundary` routes inactive, promoted, archived, deferred, revisit-candidate, unresolved, unsupported, or out-of-scope rows to boundary explanation.
• `Show usable paths` returns focus from issue clusters to selectable paths.

No global side navigation is required. If a shell exists later, Recovery Triage should remain part of the portfolio overview rather than becoming a separate admin page.

Screen-By-Screen Layout

Screen 1: Loading / Diagnostic Scan

Purpose: communicate that the tracker is reading repo-local source files and classifying recovery state.

Regions:

• Header: repository label, scan status, and source files being checked.
• Triage skeleton: blocked, warning, unresolved, and usable counts.
• Source-read progress: manifest, scoped research dirs, alignment/provenance refs when available.
• Early issue placeholder: appears as soon as parse, permission, or missing-file issues are detected.

Key behavior:

• Loading should name local source reads, not imply network activity.
• Prior loaded state, if shown, must be labelled as prior state until the current scan completes.

Screen 2: Recovery Triage Overview

Purpose: make usable, warning-level, and blocked portfolio state legible before path selection.

Regions:

• Header: product name, repository context, scan freshness.
• Triage summary: clean/warning/partial/blocked state, blocked issue count, warning count, unresolved ref count, usable path count.
• Affected-level chips: portfolio, source, path, claim, handoff.
• Blocked action summary: which clean actions are suppressed and why.
• Usable-state summary: what can still be inspected safely.

Key behavior:

• Diagnostic severity and affected level are shown separately.
• Blocking issues appear before normal path rows.
• Clean portfolios collapse this surface into a compact summary.

Screen 3: Diagnostic Clusters

Purpose: let the operator understand issue scope without entering full diagnostics recovery.

Regions:

• Blocking issues first.
• Warning-level issues second.
• Unresolved refs list.
• Permission/read errors.
• Contradictions and unsupported/inferred claims.
• Row links to affected source, path, claim, or handoff scope.

Key behavior:

• Each issue names affected refs or explains why no source ref exists.
• Issue rows expose severity, affected level, impacted paths, handoff impact, and recommended manual check.
• Issue expansion is shallow; deeper repair routes to diagnostics recovery.

Screen 4: Usability-Grouped Portfolio

Purpose: let the operator select a path after seeing recovery state.

Regions:

• `Usable now` path group.
• `Usable with warnings` path group.
• `Blocked` path group.
• `Unresolved refs` group.
• `Boundary/context` group for inactive, promoted, archived, deferred, revisit-candidate, out-of-scope, or unsupported paths.

Row content:

• Path label and ID.
• Status and boundary label.
• Pipeline stage.
• Next skill when safe, or suppression reason when unsafe.
• Scope path.
• Last touched.
• Trust level.
• Diagnostic severity and affected-level badges.
• Handoff impact.

Screen 5: Selected Path Recovery Summary

Purpose: confirm whether the selected path can advance to verification or must route to recovery/explanation.

Regions:

• Selected row highlight.
• Recovery status: usable, warning, blocked, unresolved, or boundary.
• Blocking and warning issue list scoped to the selected path.
• Available actions.
• Suppressed actions with reasons.

Key behavior:

• Primary verification action is enabled only when selected-path inspection is safe.
• Warning-level paths can continue only with warnings and diagnostic refs carried forward.
• Blocked, unresolved, contradicted, unsupported, promoted, inactive, archived, deferred, revisit-candidate, or out-of-scope rows route to recovery or explanation.

Screen 6: Empty / No-AFPS Or No-Usable-State

Purpose: avoid fabricated portfolio guidance when source state does not support orientation.

Regions:

• Source checked.
• Manifest state.
• No product paths or no usable paths explanation.
• Blocking or missing-source diagnostics.
• Manual check guidance when source evidence supports it.

Screen 7: Blocking Diagnostic Summary

Purpose: preserve orientation while making unsafe state impossible to bypass.

Regions:

• Blocking issue banner.
• Affected source files, path refs, claims, or handoff scope.
• What remains readable.
• Which actions are suppressed and why.
• Link to diagnostics recovery.

Key Components And Controls

Components:

• Repository scan header.
• Recovery triage summary.
• Diagnostic severity cluster.
• Affected-level chip group.
• Blocked-action summary.
• Usable-state summary.
• Usability-grouped path list.
• Diagnostic issue row.
• Product-path row with diagnostic impact.
• Selected path recovery summary.
• Blocking diagnostic banner.
• Empty/no-usable-state panel.

Controls:

• Filter by severity: usable, warning, blocked, unresolved, boundary.
• Filter by affected level: portfolio, source, path, claim, handoff.
• Select path row.
• Open diagnostics recovery.
• Inspect affected source.
• Continue to verify selected path.
• Explain boundary for inactive/promoted/out-of-scope rows.

Avoid:

• Primary copy-next-command button.
• Repair/edit/write-back controls.
• Hidden warning or blocked state behind hover-only interactions.
• Full diagnostic repair queues inside the orientation branch.
• A single aggregate health score that hides which action is blocked.

Button And Link Behavior

Primary button: `Continue to verify path`.

Enabled when:

• A product path is selected.
• The selected path is usable or warning-level.
• Required source state for selected-path inspection is not contradicted, unreadable, malformed, unresolved, promoted-boundary, or out-of-scope.
• Warning context and diagnostic refs can be carried forward.

Disabled or suppressed when:

• No path is selected.
• The path is blocked, unresolved, contradicted, unsupported, out-of-scope, inactive, promoted, archived, deferred, or revisit-candidate.
• Required selected-path source support is missing, unreadable, malformed, or permission-denied.
• The only available next action would be a clean handoff or next command without warning preservation.

Secondary links:

• `Open diagnostics recovery`: routes to the sibling recovery flow for the selected issue or portfolio-level block.
• `Inspect affected source`: routes to source/provenance inspection for the affected source, claim, or path.
• `Show usable paths`: focuses the safe/warning path groups.
• `Explain boundary`: routes inactive, promoted, archived, deferred, revisit-candidate, unresolved, unsupported, or out-of-scope rows to boundary explanation.

Links must preserve source paths, issue IDs, selected path ID, trust level, parser confidence, source confidence, source status, warning IDs, affected level, handoff impact, and diagnostic refs.

Spatial Density, Sizing, And Hierarchy

Density: medium to data-dense.

Hierarchy:

1. Blocking and warning state.
2. Affected scope and blocked action reasons.
3. What remains usable.
4. Usable and warning-level path groups.
5. Blocked/unresolved/boundary context groups.
6. Secondary source, provenance, and diagnostics actions.

The layout should make issue severity unavoidable without hiding selectable rows. A top triage band can lead into a two-column desktop arrangement: diagnostic clusters on one side and usability-grouped paths on the other. Path rows should remain scan-friendly and should not become a full log table.

The visual feel should be operational, direct, and calm under failure. Warning and blocked states need enough contrast to prevent false confidence, but the page should still show progress and usable scope instead of feeling like a dead end.

Responsive Behavior

Desktop:

• Recovery triage spans the top.
• Diagnostic clusters and usability-grouped path list can sit side by side.
• Selected path recovery summary may appear as a right-side panel or inline expansion.

Tablet:

• Triage summary stacks into severity and affected-scope rows.
• Diagnostic clusters appear above path groups.
• Path rows retain label, status, trust, severity, affected level, and selected action.

Mobile:

• Severity summary appears first as stacked blocks.
• Affected-level filters collapse into a simple segmented control or menu.
• Diagnostic clusters appear before path groups, with compact issue rows.
• Path rows become list items with visible severity and warning badges.
• No horizontal table should be required for first value.

Visual Tone

Tone: recovery-oriented, precise, source-native, and controlled.

The page should communicate that AFPS Tracker is useful even when the repo is imperfect because it tells the operator what can still be trusted. Clean states may collapse into an efficient overview, but warning and blocked states should use plain labels, affected source refs, and disabled-action reasons.

Avoid alarmist styling, generic error pages, decorative gradients, mascot-like empty states, and abstract "health score" visuals. The page should feel like a local operator triage surface, not incident-management theater.

Strengths

• Strongest safety posture when source state is stale, missing, contradictory, or unreadable.
• Prevents false confidence before path selection.
• Makes unresolved active refs and blocked actions first-class orientation objects.
• Shows what remains usable instead of forcing an all-or-nothing failure state.
• Provides a meaningful contrast against quick-scan and trust-first variants.

Risks And Failure Modes

• The first screen may overemphasize exceptions in clean repositories.
• Recovery triage can drift into the full `uf-recover-diagnostics` branch.
• Operators may feel delayed if they primarily want active path selection.
• Dense diagnostic clusters can obscure the simple "what path do I inspect next?" question.
• A blocked-action summary could look like final remediation guidance if the UI over-specifies repair steps.

Mitigations:

• Collapse triage to a compact clean-state summary when there are no issues.
• Keep usable path groups visible on the same surface as diagnostic clusters.
• Route repair and deep source verification to sibling branches.
• Frame recommendations as "inspect" or "recover" routes, not write-back fixes.
• Keep the primary action framed as selected-path verification, never final handoff.

Implementation Complexity

Estimated complexity: medium to high.

Reasons:

• Requires diagnostic clustering by severity and affected level.
• Needs careful propagation from portfolio/source diagnostics to path usability groups.
• Must support blocked-action explanations and safe partial orientation.
• Still uses existing read models and does not require write-back, collaboration, or repair mechanics.

Implementation-sensitive areas:

• Separating diagnostic severity from affected scope.
• Grouping paths by usability without losing original status/boundary state.
• Preserving unresolved refs as visible objects.
• Showing blocked reasons without implying repair has happened.
• Responsive handling of diagnostic clusters and path selection.

What UI Review Should Validate First

UI review should validate whether diagnostics-first orientation improves safety without making clean or warning repositories feel unusable.

Priority validation questions:

• Can the operator immediately tell what is usable, warning-level, blocked, unresolved, and boundary-routed?
• Are blocking reasons and affected source refs visible before path selection?
• Can the operator still find and select a safe active path quickly?
• Does the page avoid becoming a full diagnostics repair workflow?
• Do warning-level paths carry caveats forward into selected-path verification?
• Does the page make inactive, promoted, archived, deferred, revisit-candidate, unsupported, unresolved, and out-of-scope states impossible to mistake for active work?

User Signal For UI Interview Readiness

This branch is ready for `$ui-interview` if a reviewer agrees that AFPS Tracker's orientation should prioritize recovery clarity: the user needs to know what remains usable, what is warning-level, and what is blocked before selecting a path.

Strong positive signal:

• The reviewer can identify the blocked issue, affected scope, and usable path group without reading raw files.
• The reviewer can select a warning-level path and explain which caveats must travel forward.
• The reviewer trusts that unsafe next-command or handoff behavior is suppressed.

Negative signal:

• The reviewer says clean-repo use feels slowed by failure-first framing.
• The reviewer cannot find the safe active path quickly.
• The page feels like a repair dashboard rather than orientation.
• Diagnostic detail hides the portfolio structure.

Future Experiment Target

If this variation later receives UI approval, a future experiment route could be named `/experiments/diagnostics-first-recovery`. Default progression-mode rules still apply: no prototype buildout or route implementation should be written from this UX variation alone before an approved `$ui-interview` branch exists.

Portfolio-Map Grouping Full Intermediate Spec

design/afps-tracker/ux-variations-uf-orient-portfolio/portfolio-map-grouping.md

skill: ux-variations
topic: uf-orient-portfolio
product_path: research/afps-tracker
parent_flow_branch: uf-orient-portfolio
variation_id: portfolio-map-grouping
status: intermediate
source_command: "$ux-variations uf-orient-portfolio"
brief: design/afps-tracker/_working/ux-variations-uf-orient-portfolio-brief.md
flow_tree: design/afps-tracker/flow-tree-afps-tracker.yaml
user_flow: design/afps-tracker/user-flow-afps-tracker.md
domain_model: design/afps-tracker/domain-model-afps-tracker.md
model_tree: design/afps-tracker/model-tree-afps-tracker.yaml

Portfolio-Map Grouping

Design Thesis

Portfolio-Map Grouping makes the AFPS portfolio itself spatially legible. The operator should open AFPS Tracker and see active, parallel, inactive, deferred, archived, promoted, unresolved, unsupported, and out-of-scope groups as a branch-state map, with active selection emerging from the broader state neighborhood.

The variation treats orientation as a topology problem. It assumes the operator manages multiple product paths and needs to understand why each branch exists, which paths are currently inspectable, and which paths are context rather than active next work. The first object of attention is the portfolio map, not a compact list, trust console, diagnostics queue, or resume command.

Target User Fit

Best fit: AFPS operator or AI workflow maintainer managing a repo with multiple active, parallel, inactive, promoted, or boundary-state product paths.

Usage context:

• The operator needs to understand the whole branch landscape before selecting one path.
• Multiple product paths exist and their relationships or states matter.
• The user may need to explain why a branch is inactive, promoted, archived, or out of scope.
• The operator wants active paths visible in context rather than isolated at the top of a table.

Poor fit:

• The repo has only one active path and little branch-state context.
• The user wants the fastest possible selected path.
• The first concern is source health or diagnostic recovery rather than portfolio comprehension.
• The session goal is direct next-command continuity.

Parent Flow And Branch Relationship

Parent user-flow branch: `uf-orient-portfolio`.

Branch boundary: open tracker, scan portfolio, understand active and parallel paths, and select a path for deeper inspection. This variation changes the mental model inside orientation: paths are grouped spatially by branch state and usability. It must not absorb selected-path verification, source/provenance inspection, diagnostics recovery, handoff/export, or inactive/promoted boundary explanation.

Logical substrate preserved:

• `RepositoryContext` triggers and displays the portfolio read-through and source health caveats.
• `PortfolioSnapshot` provides active/excluded/unresolved refs, path groups, snapshot state, parser confidence, and source confidence.
• `PortfolioPathRef` preserves unresolved, inactive, boundary, and excluded refs so the map can show non-active context.
• `ProductPath` map nodes carry source status, path state, boundary kind, pipeline stage, next skill, trust level, and handoff eligibility.
• `DiagnosticIssue` affects map nodes and lanes through warnings, blocked badges, and suppressed action reasons.
• Trust-bearing map nodes preserve `trust_level`, `parser_confidence`, `source_confidence`, `warnings[]`, and `diagnostic_refs[]`.

Page And Flow Changes

This variation makes `Portfolio Map` the dominant first surface. Product paths are displayed as state-grouped nodes or lane cards: active and parallel paths remain prominent, but inactive, deferred, archived, promoted, unresolved, and out-of-scope groups stay visible as branch-state context.

Primary flow:

1. Open AFPS Tracker on an existing repository.
2. See a branch-state map with active, parallel/context, inactive/deferred, promoted, unresolved, and blocked/out-of-scope regions.
3. Scan the state neighborhoods and source caveats.
4. Select a path node from the map.
5. Continue to selected-path verification, diagnostics recovery, or boundary explanation based on the node state.

Secondary paths:

• If there is exactly one active path, the active lane remains primary but surrounding context explains whether there are inactive, promoted, or unresolved neighboring branches.
• If warnings exist, map nodes inherit visible caveat badges without turning the page into diagnostics triage.
• If blocking diagnostics exist, affected map regions show blocked overlays and suppressed-route reasons while unaffected regions remain usable.
• If no paths exist, the map becomes an empty/no-AFPS state with checked source paths rather than a fabricated board.

Progression Model

Progression is spatial-map-first and node-selection-second.

The user advances by reading branch-state neighborhoods, comparing active and non-active groups, and selecting the node that matches their current intent. The UI does not require a row table, wizard, diagnostics acknowledgement, or command search before selection.

How this differs from sibling concepts:

• Unlike Quick-Scan Overview, grouping is spatial and explanatory rather than compact active-first rows.
• Unlike Trust-First Source Health, source trust appears as node and lane caveats rather than the first full workspace.
• Unlike Diagnostics-First Recovery, blocked and warning state modifies map regions but does not define the whole page structure.
• Unlike Command/Resume-First Orientation, the first object is portfolio topology, not a provisional next-work answer.

Completion criteria:

• The user can identify active and parallel paths in relation to inactive, deferred, promoted, unresolved, and out-of-scope context.
• The user can explain why non-active branches are not normal active next work.
• The user can select a path node for verification or route boundary nodes to explanation.
• The map does not imply that cards are draggable, editable, or writable source truth.

Onboarding And Activation Model

First-run onboarding is spatial and label-driven.

Initial frame:

• Scan status names repo-local source files being checked.
• A small map legend defines active, parallel/context, inactive/deferred, promoted, unresolved, warning, blocked, and out-of-scope states.
• Source-health caveats appear as global and node-level badges.
• The active lane is visually emphasized without hiding boundary/context lanes.

Activation moment:

The operator reaches first value when the branch-state map explains what paths exist, which ones are active, why surrounding branches are not active next work, and which node can be selected for deeper inspection.

The page should avoid tutorial copy. The map structure, lane labels, badges, and disabled-action reasons should carry the explanation.

Typical Workflow Sequence

1. Repository scan begins and renders a map skeleton with lane placeholders.
2. The map resolves into state lanes or grouped regions.
3. Active paths appear in the primary lane with stage, next skill, trust, and warning indicators.
4. Parallel/context groups show inactive, deferred, archived, revisit-candidate, promoted, unresolved, unsupported, and out-of-scope nodes.
5. The operator hovers, focuses, or selects a node.
6. A compact node detail panel summarizes selected state, source status, warnings, boundary kind, and available route.
7. The primary action continues to selected-path verification for active/warning-level nodes.
8. Boundary, unresolved, blocked, or promoted nodes route to boundary explanation or diagnostics recovery instead of normal active verification.

Sharing, Collaboration, And Permissions Model

This variation assumes solo evaluator use by default. It does not introduce account roles, collaboration, comments, invitations, or permissions.

The map may support explanatory handoff later by making branch state legible, but copy/export controls are not primary in this branch. Any future share-like behavior must preserve source warnings, boundary labels, and route suppression.

Permission-denied source reads are represented as node or lane caveats. Unaffected map regions remain visible when partial source-backed data is available.

Return-Use And Notification Model

Return use is portfolio-shape refresh.

Re-entry triggers:

• Opening the repo after context loss and needing the branch landscape.
• Returning after a product path was archived, deferred, promoted, or split.
• Reviewing why parallel product paths exist.
• Explaining why a branch is context only rather than active next work.

The page does not use notifications. It should show scan freshness and last-touched values on nodes, with clear labels when prior map state is being replaced by a fresh repo-local scan.

Failure Recovery And Abandoned-Workflow Behavior

Recovery is visible as map state but not the dominant workflow.

Failure states:

• Missing progress manifest: show no-map state with checked source and no fabricated lanes.
• Malformed manifest: show blocked map overlay and suppress clean route actions.
• Unresolved active ref: show unresolved node in an unresolved lane or region.
• Missing scoped path: keep manifest-backed node visible and mark scoped support unavailable.
• Permission denied: label affected source and affected nodes, preserving readable lanes.
• Contradictory status: show contradiction badge on node and suppress clean next action.
• Promoted or inactive path selected: route to boundary explanation with branch-state context.

Abandoned workflow:

If the user leaves after scanning the map but before selecting, no state write-back occurs. On return, the tracker rescans canonical files and labels scan freshness. Any remembered selected node must be visually subordinate to the current map state.

Navigation Model

Navigation is map-centered.

Primary navigation:

• Portfolio Overview opens to the Portfolio Map.
• Node selection opens a compact detail panel or inline selection summary.
• Active or warning-level nodes advance to selected-path verification.

Secondary navigation:

• `Inspect warnings` routes to diagnostics scoped to the selected node or lane.
• `Inspect source` routes to source/provenance inspection after node selection.
• `Explain boundary` routes inactive, promoted, archived, deferred, revisit-candidate, unresolved, unsupported, or out-of-scope nodes to boundary explanation.
• `Switch to list` may be a UI-review option if the map becomes hard to scan, but it should not become the primary variation thesis.

A global side nav is optional. If a shell exists later, the map remains the first meaningful screen for this variation.

Screen-By-Screen Layout

Screen 1: Loading / Map Scan

Purpose: communicate that the tracker is reading repo-local source files and preparing a source-derived branch-state map.

Regions:

• Header: repository label and scan status.
• Map skeleton: lane placeholders for active, context, boundary, and unresolved groups.
• Source-health placeholder: warning and blocked counts when detected early.
• Legend skeleton: state badges and map grouping labels.

Key behavior:

• Loading should not imply network activity.
• Prior map state, if shown, must be labelled as prior state until the current scan completes.

Screen 2: Portfolio Map

Purpose: let the operator understand the whole branch landscape.

Regions:

• Header: product name, repository context, scan freshness.
• Compact source-health strip: clean/warning/blocked status, parser confidence, source confidence, unresolved refs.
• Map legend: active, parallel/context, inactive/deferred, archived, promoted, unresolved, unsupported, out-of-scope, warning, blocked.
• Map lanes or regions: active, parallel/context, inactive/deferred/archive, promoted/boundary, unresolved/blocked.
• Node detail rail or inline selected-node preview.

Key behavior:

• Active paths are easy to find but not detached from branch-state context.
• Warnings and blocked states are visible on affected nodes and lanes.
• Boundary nodes are selectable for explanation but not routed as active next work.

Screen 3: Active And Parallel Neighborhood

Purpose: show active paths beside nearby context.

Regions:

• Active lane with active path nodes.
• Parallel/context lane with related or sibling product paths.
• Node metadata: status, stage, next skill or suppression reason, last touched, trust level, warning count.
• Relationship hints when source evidence supports them, such as same product family, promoted predecessor, or parallel exploration.

Key behavior:

• Relationship hints must be source-backed or explicitly caveated.
• The map should not invent hierarchy or dependency if source evidence does not support it.

Screen 4: Boundary And Context Groups

Purpose: explain why non-active branches exist without turning them into active routes.

Regions:

• Inactive/deferred/revisit group.
• Archived group.
• Promoted boundary group.
• Out-of-scope/unsupported group.
• Unresolved refs group.

Key behavior:

• Boundary groups remain visible as context.
• Selecting a boundary node opens explanation route, not active verification.
• Promoted paths explicitly hand off out of AFPS Tracker scope when supported.

Screen 5: Selected Node Preview

Purpose: confirm selected map node and available route.

Regions:

• Selected node highlight.
• Compact detail panel: label, ID, status, pipeline stage, scope path, trust level, warnings, boundary kind, next skill or suppression reason.
• Primary action: continue to verification for active/warning nodes.
• Secondary actions: inspect warnings, inspect source, explain boundary.

Key behavior:

• The primary action is disabled or replaced for blocked, unresolved, inactive, promoted, archived, deferred, revisit-candidate, unsupported, or out-of-scope nodes.
• Clean next-command copy is not offered in this branch.
• Warning context is carried forward when verification is allowed.

Screen 6: Empty / No-AFPS Map

Purpose: avoid fabricated map structure when source evidence does not support it.

Regions:

• Source checked.
• Manifest state.
• Explanation that no AFPS product paths were found.
• Diagnostic details if source evidence supports them.

Screen 7: Blocked Map State

Purpose: preserve map context while preventing false confidence.

Regions:

• Blocking issue banner.
• Affected lanes and nodes.
• Readable unaffected lanes.
• Suppressed actions with explicit reasons.
• Link to diagnostics recovery.

Key Components And Controls

Components:

• Repository scan header.
• Compact source-health strip.
• Map legend.
• State lane or grouped region.
• Product-path node.
• Boundary node.
• Unresolved ref node.
• Node trust badge.
• Node diagnostic badge.
• Relationship hint.
• Selected-node preview.
• Empty/no-map state.
• Blocked map overlay.

Controls:

• Select path node.
• Filter or focus state lanes.
• Toggle compact/expanded nodes.
• Open node warnings.
• Continue to verify selected path.
• Explain boundary for inactive/promoted/out-of-scope nodes.
• Open diagnostics recovery for blocked nodes.

Avoid:

• Drag-and-drop movement.
• Write-back/edit controls.
• Primary copy-next-command button.
• Hidden warnings behind hover-only interactions.
• Visual relationships not backed by source evidence or explicit caveats.

Button And Link Behavior

Primary button: `Continue to verify path`.

Enabled when:

• A product path node is selected.
• The node is active or warning-level and not blocked by source contradiction, unreadable required source, malformed source, promoted boundary, or out-of-scope boundary.
• Warning context and diagnostic refs can be carried forward.

Disabled or replaced when:

• No node is selected.
• The node is inactive, promoted, archived, deferred, revisit-candidate, unresolved, contradicted, unsupported, out-of-scope, or blocked.
• Required selected-path source support is missing, unreadable, malformed, or permission-denied.

Secondary links:

• `Inspect warnings`: opens diagnostics scoped to node or lane.
• `Inspect source`: opens source/provenance inspection for selected node.
• `Explain boundary`: routes boundary/context nodes to explanation.
• `Show map context`: returns from selected-node preview to full map focus.

Links must preserve source paths, warning IDs, selected path ID, node state, boundary kind, trust level, parser confidence, source confidence, relationship caveats, and diagnostic refs.

Spatial Density, Sizing, And Hierarchy

Density: comfortable to medium.

Hierarchy:

1. Map legend and source-health strip.
2. Active lane or region.
3. Parallel/context lane.
4. Boundary, promoted, unresolved, and blocked regions.
5. Selected-node detail.
6. Secondary diagnostics/source actions.

The desktop layout can use horizontal lanes, a grouped board, or a compact map grid. It should avoid oversized cards and decorative canvas complexity. Nodes need stable dimensions so labels, badges, and warning states do not resize the map unpredictably.

The visual feel should be source-aware and spatial, but still utilitarian. The map is for comprehension and selection, not project management.

Responsive Behavior

Desktop:

• Map lanes occupy the main region.
• Source-health strip and legend sit above the map.
• Selected-node preview appears as a right-side panel or inline expansion.

Tablet:

• Lanes stack vertically by priority: active, parallel/context, boundary/context, unresolved/blocked.
• Nodes become compact cards with visible state and warning badges.
• Legend remains visible as a collapsible block.

Mobile:

• Map becomes grouped sections rather than a horizontal board.
• Active and parallel groups appear first, followed by boundary/context groups.
• Node preview appears below the selected node.
• Filters become simple group toggles.
• No horizontal scrolling should be required for first value.

Visual Tone

Tone: spatial, calm, source-native, and explanatory.

The page should make branch-state complexity feel organized without implying that AFPS Tracker owns or edits branch state. Active paths should feel selectable. Boundary and unresolved paths should feel intentionally present but clearly non-active.

Avoid decorative node graphs, heavy gradients, cartoonish boards, generic kanban status movement, and visual affordances that imply drag/drop workflow editing. Use direct labels, badges, and source caveats.

Strengths

• Best fit for understanding a multi-path AFPS portfolio.
• Makes inactive, promoted, unresolved, and boundary states visible instead of hiding them below active rows.
• Helps explain why branches exist and why they are or are not active next work.
• Provides a strong contrast against list-first, trust-first, recovery-first, and command-first variations.
• Supports future boundary explanation flows naturally.

Risks And Failure Modes

• Spatial grouping can feel heavier than necessary for a single active path.
• Map lanes can imply project-management workflow movement if not carefully labeled.
• Relationship hints may accidentally invent source truth if unsupported.
• Active path selection can become slower than in a compact list.
• Boundary context can crowd the first-value moment when many inactive paths exist.

Mitigations:

• Collapse empty or low-value lanes.
• Keep active and parallel groups visually primary.
• Label map state as source-derived and read-only.
• Require relationship hints to be source-backed or caveated.
• Provide a compact node preview and clear primary action.

Implementation Complexity

Estimated complexity: medium to high.

Reasons:

• Requires spatial grouping and responsive lane behavior.
• Needs clear node state, boundary, warning, and trust badge composition.
• Must avoid drag/drop or write-back implications.
• Uses existing read models but demands stronger visual grouping logic than list-first variants.

Implementation-sensitive areas:

• Source-derived lane assignment.
• Stable node sizing across labels and badges.
• Handling many inactive or archived paths without overwhelming active paths.
• Preserving unresolved refs as visible nodes.
• Responsive transformation from map lanes to mobile grouped sections.

What UI Review Should Validate First

UI review should validate whether spatial grouping improves portfolio comprehension without slowing active path selection too much.

Priority validation questions:

• Can the operator identify active and parallel paths in context?
• Do inactive, deferred, archived, promoted, unresolved, unsupported, and out-of-scope branches read as context rather than active routes?
• Does the map avoid implying drag/drop or write-back?
• Are warnings and source caveats visible on affected nodes?
• Can the operator select a path and understand the correct downstream route?
• Does the mobile layout still preserve branch-state context without horizontal scrolling?

User Signal For UI Interview Readiness

This branch is ready for `$ui-interview` if a reviewer agrees that AFPS Tracker should lead orientation with spatial portfolio comprehension: the user needs to see active and non-active branch neighborhoods before selecting a path.

Strong positive signal:

• The reviewer can explain the portfolio shape and branch-state boundaries without reading raw files.
• The reviewer can select an active path while understanding nearby inactive/promoted/unresolved context.
• The reviewer does not mistake boundary nodes for normal active next work.

Negative signal:

• The reviewer says a compact list would answer the orientation job faster.
• The map feels like a writable kanban board.
• Boundary/context groups crowd out active path selection.
• Relationship hints feel unsupported or speculative.

Future Experiment Target

If this variation later receives UI approval, a future experiment route could be named `/experiments/portfolio-map-grouping`. Default progression-mode rules still apply: no prototype buildout or route implementation should be written from this UX variation alone before an approved `$ui-interview` branch exists.

Command/Resume-First Orientation Full Intermediate Spec

design/afps-tracker/ux-variations-uf-orient-portfolio/command-resume-first-orientation.md

skill: ux-variations
topic: uf-orient-portfolio
product_path: research/afps-tracker
parent_flow_branch: uf-orient-portfolio
variation_id: command-resume-first-orientation
status: intermediate
source_command: "$ux-variations uf-orient-portfolio"
brief: design/afps-tracker/_working/ux-variations-uf-orient-portfolio-brief.md
flow_tree: design/afps-tracker/flow-tree-afps-tracker.yaml
user_flow: design/afps-tracker/user-flow-afps-tracker.md
domain_model: design/afps-tracker/domain-model-afps-tracker.md
model_tree: design/afps-tracker/model-tree-afps-tracker.yaml

Command/Resume-First Orientation

Design Thesis

Command/Resume-First Orientation starts from the operator's immediate return question: what can I safely do next, and why? The operator should open AFPS Tracker and first see a provisional resume answer, suppressed-command reason, or branch-state explanation, then inspect the supporting portfolio paths and source warnings before selecting a path.

The variation treats orientation as continuity restoration. It assumes the operator or a follow-on agent is returning after context loss, compaction, handoff, or a direct "what next?" prompt and needs a source-caveated next-work posture without reading the raw AFPS files first.

This branch does not make final handoff/export primary. It previews next-work eligibility inside orientation and routes the operator to selected-path verification, diagnostics recovery, boundary explanation, or the later `uf-handoff-resume` branch when they need a copyable final handoff.

Target User Fit

Best fit: AFPS operator, future self, or agent session that needs to resume a research workflow quickly while preserving source-trust caveats.

Usage context:

• The operator arrives from a session handoff, context compaction, or restart.
• The first question is "what can I safely run or inspect next?"
• There may be multiple active paths, so the UI must explain why a resume answer is selected, ambiguous, warning-level, or suppressed.
• The likely next branch is selected-path verification before any clean copyable command.

Poor fit:

• The operator wants broad portfolio topology more than immediate resume posture.
• The repo is known damaged and diagnostic triage should dominate.
• The user wants complete evidence/provenance review before any next-work framing.
• The session goal is a final exported handoff rather than orientation.

Parent Flow And Branch Relationship

Parent user-flow branch: `uf-orient-portfolio`.

Branch boundary: open tracker, scan portfolio, understand active and parallel paths, and select a path for deeper inspection. This variation changes the first object of attention from path list, source-health console, recovery triage, or map topology to a provisional next-work posture. It must not absorb selected-path verification, evidence/provenance inspection, diagnostics recovery, export/handoff finalization, or inactive/promoted boundary explanation.

Logical substrate preserved:

• `RepositoryContext` triggers the repo read-through and provides scan state, source health, and warnings.
• `PortfolioSnapshot` provides active path refs, excluded refs, unresolved refs, parser confidence, source confidence, and portfolio-level diagnostics.
• `PortfolioPathRef` preserves active, inactive, boundary, excluded, and unresolved refs so resume answers cannot silently omit unsafe source state.
• `ProductPath` supplies path state, pipeline stage, next skill, trust level, handoff eligibility, boundary kind, and route suppression.
• `DiagnosticIssue` affects whether a resume answer is clean, warning-level, blocked, ambiguous, or explanatory.
• `HandoffSummary` semantics are previewed only as eligibility and suppression state; final generation and copy behavior remains owned by `uf-handoff-resume`.

Page And Flow Changes

This variation makes a `Resume Answer` or `Command Posture` module the dominant first surface inside the portfolio overview. It still shows active and parallel paths, but those paths are organized around the immediate resume question: clean next work, warning next work, ambiguous multiple paths, blocked, boundary-only, or no safe command.

Primary flow:

1. Open AFPS Tracker on an existing repository or from a resume prompt.
2. See a provisional resume card that states the safest current next-work posture.
3. Review why that posture exists: selected/eligible path, competing active paths, warnings, blocked reasons, route suppression, or boundary status.
4. Select or confirm a product path from the supporting path list.
5. Continue to selected-path verification, diagnostics recovery, boundary explanation, or later handoff generation based on the selected path state.

Secondary paths:

• If exactly one active path is clean enough to inspect, the resume card can say that selected-path verification is available and name the source-backed next skill.
• If multiple active paths exist, the resume card states that selection is required and shows the competing active paths before any command-like output.
• If warning-level issues exist, the resume card can show a warning posture but must preserve caveats and avoid clean-copy language.
• If blocked diagnostics exist, the resume card leads with the suppressed-command reason and the affected source or path.
• If the path is promoted, inactive, archived, deferred, unresolved, unsupported, or out of scope, the resume card explains why normal active routing is suppressed.

Progression Model

Progression is resume-answer-first and evidence-of-eligibility-second.

The user advances by reading the current next-work posture, understanding why the posture is clean, warning-level, blocked, ambiguous, or explanatory, then choosing the path or recovery route that makes the posture actionable. The UI does not require scanning the entire portfolio first, but it must keep supporting path state and source warnings visible enough to prevent blind command trust.

How this differs from sibling concepts:

• Unlike Quick-Scan Overview, the first object is a resume answer or suppressed-command reason, not a compact portfolio list.
• Unlike Trust-First Source Health, trust data is framed around whether next work is safe rather than as a general source-health console.
• Unlike Diagnostics-First Recovery, diagnostics matter because they block or caveat resume posture; they do not define the whole page.
• Unlike Portfolio-Map Grouping, branch-state context supports the answer but is not the primary spatial object.

Completion criteria:

• The user can say whether there is a safe next-work posture, a warning-level posture, an ambiguous multiple-path posture, or no safe command.
• The user can see which product path or source condition caused that posture.
• The user can select a path for verification or route to recovery/boundary explanation.
• The UI does not emit a clean copyable next command before selected-path trust is verified by downstream flows.

Onboarding And Activation Model

First-run onboarding is phrased as resume continuity.

Initial frame:

• A scan status names repo-local source files being checked.
• The resume card starts in a neutral `Checking current AFPS state` posture.
• A compact legend distinguishes `ready to inspect`, `select path first`, `warning`, `blocked`, `boundary`, and `no AFPS state`.
• Source caveats appear in the card, not only in secondary rows.

Activation moment:

The operator reaches first value when they know what they can safely inspect next, why any command-like action is available or suppressed, and which path to select for verification.

The page should avoid tutorial copy. The resume answer, suppression reason, path chips, warning labels, and primary action state should make the model obvious.

Typical Workflow Sequence

1. Repository scan begins with `ScanPortfolio`.
2. Resume card resolves into one of several postures: clean inspectable path, warning inspectable path, multiple active paths, blocked, boundary-only, empty/no-AFPS state, or out-of-scope request.
3. Supporting path chips or rows show active candidates, parallel paths, unresolved refs, and boundary/context paths.
4. The operator selects the path connected to the posture or chooses a different candidate.
5. A path-linked resume explanation updates with trust level, next skill, suppression reason, warnings, and diagnostic refs.
6. The primary action routes to selected-path verification for active/warning paths, diagnostics recovery for blocked state, or boundary explanation for inactive/promoted/out-of-scope state.
7. A final handoff/copy affordance remains absent or disabled until later verification/handoff branches make it safe.

Sharing, Collaboration, And Permissions Model

This variation assumes solo evaluator and agent-resume use. It does not introduce accounts, comments, invitations, review assignments, collaborative status, or role permissions.

Share-like behavior is represented only as provisional handoff readiness:

• The page can show what a later handoff might say at a high level.
• It must not offer clean copy unless the downstream handoff branch has established eligibility.
• Warning-level posture must include warnings and source refs in any preview.
• Blocked, promoted, inactive, unresolved, or out-of-scope posture must suppress normal route language.

Permission-denied source reads directly affect resume posture. If an inaccessible file supports the selected path's next skill, the card must show blocked or warning state instead of clean continuity.

Return-Use And Notification Model

Return use is the primary case.

Re-entry triggers:

• Opening AFPS Tracker after a session restart or context compaction.
• Starting a new agent session and needing the next safe AFPS command or inspection target.
• Returning from an alignment page or progress manifest after partial work.
• Asking why a previously suggested command is now blocked, ambiguous, or suppressed.

The page does not use notifications. It relies on scan freshness, source status, last touched values, and explicit posture labels. If prior resume state is remembered by a later implementation, it must be marked as prior and replaced by the current source read once the scan completes.

Failure Recovery And Abandoned-Workflow Behavior

Recovery is expressed as route suppression and next-step posture.

Failure states:

• Missing progress manifest: resume card shows no-AFPS-state, source checked, and no fabricated command.
• Malformed manifest: parser failure suppresses clean command posture and points to diagnostics recovery.
• Multiple active paths: resume card avoids choosing silently and asks for path selection.
• Unresolved active ref: card shows ambiguous or blocked posture and keeps unresolved ref visible.
• Missing scoped path: card marks selected path partial or warning-level and suppresses source-backed command certainty.
• Permission denied: affected source path is named and clean posture is suppressed when relevant.
• Contradictory status or next skill: card shows contradiction and blocks clean next-work language.
• Promoted path: card uses promoted-boundary posture and routes to boundary explanation or separate execution tracker context when supported.
• Inactive, archived, deferred, revisit-candidate, unsupported, unresolved, or out-of-scope path: card explains why normal active routing is suppressed.

Abandoned workflow:

If the user leaves after reading the resume card but before selecting, no state write-back occurs. On return, the tracker rescans canonical files. Any previously selected or suggested path must be visually subordinate to fresh source state.

Navigation Model

Navigation is command-posture-centered.

Primary navigation:

• Portfolio Overview opens with the Resume Answer card in primary focus.
• Path chips or rows below the card let the user choose or change the candidate path.
• Active or warning-level selections route to selected-path verification.

Secondary navigation:

• `Why suppressed?` routes to diagnostics recovery or boundary explanation depending on cause.
• `Inspect source for this answer` routes to source/provenance inspection after a path or claim is selected.
• `Show all paths` expands the supporting portfolio list when the operator needs broader context.
• `Prepare handoff` is deferred to `uf-handoff-resume`; in this branch it appears only as disabled or "available after verification" language.

A global side nav is optional. If present later, the resume answer remains the first meaningful object on the overview.

Screen-By-Screen Layout

Screen 1: Loading / Resume Check

Purpose: communicate that AFPS Tracker is reading repo-local sources to determine safe resume posture.

Regions:

• Header: repository label, source read status, and scan freshness placeholder.
• Resume card skeleton: `Checking current AFPS state`.
• Candidate path skeleton: active refs and path rows loading.
• Caveat placeholder: early parse, permission, or missing-file warnings.

Key behavior:

• Loading should not imply network activity.
• Prior resume answer, if shown, must be labelled as prior until the current scan completes.

Screen 2: Resume Answer Card

Purpose: answer what can safely happen next before the operator scans every path.

Regions:

• Posture label: ready to inspect, select path first, warning, blocked, boundary, empty, or out of scope.
• Candidate path: label, ID, status, stage, scope path, and next skill when safe.
• Reason line: why this posture exists.
• Trust envelope: trust level, parser confidence, source confidence, warning count, diagnostic refs.
• Primary action: continue to verification, choose path, open diagnostics, explain boundary, or no safe action.

Key behavior:

• The card must distinguish provisional inspection from final copyable handoff.
• Clean command-like language appears only when source state supports inspection and still routes to verification.
• Suppression reasons are first-class, not hidden in tooltips.

Screen 3: Supporting Path Candidates

Purpose: show the portfolio evidence behind the resume card.

Regions:

• Active candidate chips or rows.
• Parallel/context paths.
• Unresolved refs.
• Boundary/context paths.
• Warning and blocked badges.

Row content:

• Path label and ID.
• Status and boundary label.
• Pipeline stage.
• Next skill or suppression reason.
• Scope path.
• Last touched.
• Trust level.
• Parser/source confidence pair.
• Warning/diagnostic count.

Key behavior:

• Multiple active paths require explicit selection.
• Boundary rows are selectable for explanation but never become clean active routes.
• Candidate order must be source-derived and caveated; no autonomous recommendation is implied without evidence.

Screen 4: Selected Candidate Resume Explanation

Purpose: connect a selected path to its safe or suppressed next-work posture.

Regions:

• Selected path header.
• Resume explanation: next skill, inspection target, or route suppression reason.
• Source-health excerpt: affected files, parser/source confidence, warnings.
• Available route: verification, diagnostics recovery, source/provenance inspection, or boundary explanation.
• Deferred handoff note: copyable handoff becomes available only after downstream verification/handoff flow.

Key behavior:

• The selected candidate explanation should be concise enough for a resume moment.
• It should not replace selected-path detail or evidence/provenance inspection.

Screen 5: Blocked Or Ambiguous Resume State

Purpose: prevent false continuity when the next action is not safe.

Regions:

• Blocked or ambiguous posture header.
• Cause list: malformed manifest, unresolved active refs, contradictions, permission issue, multiple active paths, no AFPS state, promoted boundary, or out-of-scope request.
• Affected source refs.
• Safe alternatives: select a path, inspect diagnostics, explain boundary, or open source verification.

Key behavior:

• No clean next command appears in blocked or ambiguous states.
• The page preserves useful orientation even when command continuity is unavailable.

Key Components And Controls

• Resume Answer card with posture label, candidate path, trust envelope, and primary route.
• Candidate path chips or compact rows for active and parallel paths.
• Suppression reason block for blocked, ambiguous, promoted, inactive, unresolved, or out-of-scope states.
• Trust badges for parser confidence, source confidence, warning count, and diagnostic refs.
• Source caveat list for affected files and refs.
• `Continue to verification` button for active or warning-level selected paths.
• `Choose path` control when multiple active candidates exist.
• `Open diagnostics` button for blocked or warning posture.
• `Explain boundary` button for inactive, promoted, archived, deferred, revisit-candidate, unresolved, unsupported, or out-of-scope posture.
• `Show all paths` disclosure to expand from command posture to portfolio overview.

Button And Link Behavior

• `Continue to verification`: routes to `uf-verify-selected-path` for the selected active or warning-level path; carries warnings and diagnostic refs forward.
• `Choose path`: focuses candidate path rows or opens a compact selector; it does not auto-rank without source support.
• `Open diagnostics`: routes to `uf-recover-diagnostics` when diagnostic severity or blocked reasons require deeper review.
• `Explain boundary`: routes to `uf-explain-boundaries` for inactive, promoted, archived, deferred, revisit-candidate, unresolved, unsupported, or out-of-scope path states.
• `Inspect source for this answer`: routes to source/provenance inspection for the selected claim or path.
• `Prepare handoff`: disabled or secondary in this branch; it routes only after verification to `uf-handoff-resume`.
• `Copy next command`: absent from this orientation variation unless explicitly represented as disabled with the reason `available after verification`.

Disabled-state rules:

• Disable clean route language when blocking diagnostics exist.
• Disable normal active routing for promoted, inactive, archived, deferred, revisit-candidate, unresolved, unsupported, contradicted, or out-of-scope states.
• Disable copy-like actions unless warnings are preserved and downstream handoff eligibility is established.
• Name the reason for every disabled route.

Spatial Density, Sizing, And Hierarchy

Density: medium and focused.

Hierarchy:

1. Resume Answer card.
2. Trust and suppression reason.
3. Supporting path candidates.
4. Expanded portfolio context.
5. Secondary source/provenance/diagnostic links.

Layout guidance:

• The resume card should fit above the fold on desktop and mobile.
• Candidate path rows should be compact enough to compare multiple active paths without hiding warnings.
• Suppression reasons need enough space for affected source refs; avoid tiny tooltip-only explanations.
• Expanded all-path context should not overwhelm the primary resume card.

Responsive Behavior

Desktop:

• Resume card on the left or top, candidate path support on the right or directly below.
• Expanded all-path list can use a two-column layout: active candidates and context/boundary paths.
• Selected candidate explanation can appear as a side panel.

Tablet:

• Resume card stacks above candidate rows.
• Candidate chips can wrap into grouped rows.
• Selected explanation appears inline below the selected candidate.

Mobile:

• Resume card appears first.
• Candidate groups collapse into accordions with active candidates open by default.
• Long source paths wrap and remain copyable/selectable if implementation supports it later.
• Primary route button stays in normal flow, not sticky over content.

Visual Tone

The tone should feel like a calm operator console for source-backed continuity.

Desired qualities:

• Direct, low-drama posture labels.
• Strong disabled-state explanations.
• Clear trust badges without alarmism.
• Minimal decorative treatment.
• Command-like text only when caveated and provisional.

Avoid:

• Chatbot-style recommendation language.
• Overconfident "Run this now" copy before verification.
• Hiding warnings behind small icons.
• Treating path selection as an autonomous recommendation.
• Turning the page into a full export/handoff editor.

Strengths, Risks, And Failure Modes

Strengths:

• Best match for session-resume and agent-handoff contexts.
• Converts AFPS Tracker's value into an immediately understandable "what next?" answer.
• Makes next-command suppression visible instead of surprising.
• Keeps source warnings attached to resume posture.
• Can reduce time-to-first-value when the operator's goal is continuity rather than broad exploration.

Risks:

• May blur into `uf-handoff-resume` if copy/export controls become primary.
• Can create false confidence if the resume card looks like a final command recommendation.
• May under-serve users who need broad portfolio topology first.
• Needs precise disabled-state copy to avoid frustration when no clean command is available.
• Multiple active paths require careful ambiguity handling.

Failure modes:

• Clean next command appears despite warning, contradiction, unresolved ref, or missing provenance.
• The UI silently chooses among multiple active paths.
• Promoted or inactive paths are routed as active research work.
• Source caveats are only visible after expanding details.
• Disabled `Prepare handoff` feels like a broken feature instead of an intentional trust boundary.

Implementation Complexity

Estimated complexity: medium.

Drivers:

• Requires a derived resume-posture read model over existing portfolio state.
• Requires strong disabled/suppressed-action states.
• Requires careful distinction between provisional orientation and final handoff generation.
• Reuses the same domain substrate as other variations: `PortfolioSnapshot`, `ProductPath`, `DiagnosticIssue`, `TrustEnvelope`, and `HandoffEligibility`.

Lower-cost prototype path:

• Implement the resume card with fixture or in-memory portfolio states.
• Reuse compact path rows from the overview baseline.
• Model posture values as derived UI states: clean, warning, blocked, ambiguous, boundary, empty, and out-of-scope.
• Defer actual copy/export and parser mechanics.

What UI Review Should Validate First

UI review should validate whether the first screen communicates provisional next-work continuity without overpromising a final command.

Specific review targets:

• Does the resume card answer the "what can I safely do next?" question within seconds?
• Are warnings and route suppression visible before the operator acts?
• Is the distinction between `continue to verification` and `copy final handoff` clear?
• Does multiple-active-path ambiguity require selection rather than silent recommendation?
• Are promoted, inactive, archived, deferred, unresolved, unsupported, and out-of-scope states clearly non-routable as active next work?
• Does the UI still let the user scan supporting paths when the resume answer is blocked or ambiguous?

User Signal For `$ui-interview` Readiness

This branch is ready for `$ui-interview` when a solo evaluator can review the spec and agree that:

• Command/resume continuity is a meaningfully different first object of attention from the other four variations.
• The branch remains bounded to orientation and does not absorb final handoff/export behavior.
• Source warnings, parser/source confidence, and route suppression are preserved in every resume posture.
• The page can route to selected-path verification, diagnostics recovery, or boundary explanation without inventing new flow boundaries.
• The primary UI question for the next skill is visual treatment of the resume card, candidate paths, and suppressed-command states.

Recommended downstream UI branch label: `ui-command-resume-first-orientation`.