pdd-to-app-journeys
Internal /ace:run step — Derive expected FLW app journeys from the PDD.
SKILL.mdskills/pdd-to-app-journeys/SKILL.md
GitHubPDD to App Journeys
Generate the opp-specific expected-user-journey set that downstream app
QA grades against. Runs in Phase 2 (Scenarios & Acceptance), in
parallel with pdd-to-test-prompts. The chatbot side gets Q&A ground
truth from pdd-to-test-prompts; the app side gets UX-intent ground
truth here.
Inputs
Pipeline-only: derives journeys from a run's approved PDD, which exists only in a run.
| Source | Artifact | Used for |
|---|---|---|
| Phase 1 | 1-design/idea-to-pdd.md |
source PDD; archetype + Target FLW persona drive journey generation |
Products
2-scenarios/pdd-to-app-journeys.md— opp-specific expected-user-journey set ("expected-journeys" for short)
Consumers:
app-test-cases(Phase 3) — turns each journey into a concrete per-form test matrix once Nova has built the apps.app-ux-eval(deep QA) — LLM-as-Judge over captured screenshots + transcripts, scoring each journey's pass criteria and edge-case recovery.app-screenshot-capture(Phase 6) — uses the journey list to decide which step sequences to walk through on the AVD.
Process
Read inputs from GDrive:
- PDD:
ACE/<opp-name>/runs/<run-id>/1-design/idea-to-pdd.md
- PDD:
Read the PDD's
Archetype:field. This skill branches on archetype —atomic-visituses visit-flow journeys,focus-groupuses session-flow journeys,multi-stageproduces per-stage journeys plus a stage-transition journey. See## Archetypesbelow for the full per-archetype journey list. If the PDD has no Archetype field, default toatomic-visitbut flag it as a[WARN]in the coverage self-check.Extract persona from the PDD. Pull the persona section verbatim into the
## Personablock. The canonical name is "FLW Requirements" (pertemplates/pdd-template.md); the legacy name "Target FLW" is also accepted for older PDDs that haven't been re-rendered. If the PDD has neither section, halt — the journeys depend on knowing who the user is. Don't synthesize a persona; escalate.Generate journeys per the archetype branch. For each journey in the matching archetype branch, write:
- Goal — one-line user-outcome goal (e.g. "FLW completes a household survey and sees confirmation").
- Happy path narrative — 2-4 sentences in user-outcome language, NOT field/form mechanics. The reader should be able to picture what the FLW sees and does. Bad: "tap the next button on screen 3, fill required field household_id." Good: "FLW confirms the household by name and phone, completes screening, photographs the MTN card, and submits."
- Edge cases (UX outcomes, not error codes) — at least 2 per journey, each phrased as a UX outcome the FLW experiences, not a backend error condition. Bad: "duplicate-detection returns 409 Conflict." Good: "FLW understands why a duplicate-household submission was rejected and how to proceed."
- Pass criteria — measurable UX-level criteria that
app-ux-evalcan grade. Bad: "all required fields are non-null." Good: "Journey completes in <3 minutes including form fill" / "Required-field errors are recoverable in-form."
4a. Generate deployability-exercising journeys (the fitness surface).
Happy-path journeys alone describe a thin instrument.
pdd-to-app-journeys-eval § deployability_fitness hard-fails a
journey set that never demands the capture/validation/persistence a
deployable app needs, and app-ux-eval § capture_robustness needs a
negative path to grade. So when the PDD's Evidence Model implies it,
ALWAYS include:
- **≥1 negative-path / bad-input journey** — the FLW enters a value
the instrument should reject (blank required field, out-of-range
count, malformed phone) and experiences a clear, recoverable
rejection. This is the journey `app-test-cases` turns into a
negative-path Maestro recipe and `app-ux-eval § capture_robustness`
grades. A journey set with zero negative-path journeys is a
coverage gap, not a pass. **A low-accuracy GPS fix is NOT a member
of this set** — no build can reject one (dimagi-internal/ace#1006,
ace#1013), so a journey demanding that rejection is ungradable by
construction; it belongs under the capture-fidelity expectation
below, as an advisory the FLW sees and can act on. Before demanding
any enforcement a journey's pass criteria will be graded on, check
it against `skills/_app-component-library.md § Mechanisms a PDD
must not assert` — Table A (closed at the platform surface) and
Table B (buildable, outside ACE's toolchain today). A journey that
demands a Table A mechanism cannot pass, and a journey that calls a
Table B mechanism impossible is its own error.
- **A capture-fidelity expectation** in the relevant journey's pass
criteria — e.g. "the fix's accuracy is shown to the
FLW and submitted with every visit, and a reading worse than the
stated tolerance raises an on-screen advisory," "enumerable answers
are picked from a list, not typed,"
"an 'Other' selection prompts a specify field."
- **For multi-visit / follow-up designs, a persistence journey** —
the follow-up visit records change against the existing household,
and the change is visible/retained (the UX face of case
write-back).
Phrase all of these as UX outcomes (what the FLW sees/does), not
backend mechanics — same voice rule as the happy path. These are
*findings the journeys must demand even if the PDD only implied
them* — PDD silence is not a waiver.
Self-evaluate coverage (see
## Coverage rulesbelow):- At least one journey per archetype branch category.
- Every journey has at least one
error_recovery-flavored edge case (soapp-ux-eval's rubric has signal on recoverability). - Every journey has at least one measurable pass criterion.
- ≥1 negative-path / bad-input journey exists (step 4a) so
app-ux-eval § capture_robustnesshas signal anddeployability_fitnesscan pass. - Capture-fidelity + (for multi-visit) persistence expectations are present per step 4a where the Evidence Model implies them.
If any rule is missed, go back to step 4 and add.
Write the journeys file to
ACE/<opp-name>/runs/<run-id>/2-scenarios/pdd-to-app-journeys.md. Use the template attemplates/expected-journeys-template.mdas the skeleton.
Archetypes
ACE skills branch on the PDD's declared archetype: field. The journey
list here is what app-test-cases (Phase 3) and app-ux-eval (deep
QA) will later grade against, so getting them right for the archetype
matters: an FGD opp graded against atomic-visit-shaped journeys
produces false-positive failures in the deep app eval.
How to read a branch count
Each branch below states a DELIVER-SIDE journey count. Three things sit outside it, and reading the count as a total is how it goes wrong:
- The Learn smoke is additive. Coverage rule 4 makes
training-completion-smoke(app: learn,is_smoke: true) mandatory for every archetype that has a Learn app — i.e. all of them exceptfocus-group. It is not one of the branch categories and does not consume a slot in the branch count. - The count's FLOOR moves down on PDD deferral. Coverage rule 1 permits
skipping a category whose surface the PDD explicitly defers (no eligibility
rules → no
eligibility-edge; no photo or GPS → no photo-qualitydata-quality-error), marked[INFO]in the coverage self-check.visit-flowor its per-archetype equivalent is always required. - The count's CEILING is the branch's own category list, including the
conditional ones.
longitudinal-visitsreads 4–6 rather than 4–5 becauseregistrationis emitted whenever the entity is registered in-app, which is the common case.
These numbers are derived, not chosen — re-derive them when you add a
category. Every branch count here was smaller than the coverage rules
mandated until 2026-09-08 (longitudinal-visits said 3–5 against a compliant
floor of 6, atomic-visit 2–4 against 5), because Coverage rule 4 was added in
2026-05 and no branch count moved with it. That made both ranges unsatisfiable
while complying with the same file's blocking rules, and every longitudinal and
atomic run paid the reconciliation. Third instance of the class in this file
family after ace#1545; ace#2274 for this one. Enforced:
test/skills/journey-count-consistency.test.ts.
atomic-visit (default)
The PDD describes one FLW visit producing one structured delivery (photo + GPS + form). Examples: turmeric market survey, household data collection.
Generate 2–4 DELIVER-SIDE journeys covering the categories below. The mandatory Learn smoke from Coverage rule 4 is ADDITIONAL to this count — a two-app opp therefore emits 3–5 journeys in total. See § How to read a branch count.
- visit-flow — the happy-path walk through Connect → Deliver app → form fill → submit → confirmation. The FLW completes one full delivery end-to-end without errors.
- eligibility-edge — the FLW encounters a beneficiary who is on the boundary of the inclusion/exclusion rules. Pass criterion: the app makes the eligibility decision legible to the FLW; the FLW does not have to guess.
- data-quality-error — the FLW makes a data-entry mistake (bad GPS, blurred photo, required field skipped) and recovers in-form without losing prior input.
- duplicate-handling — the FLW visits a household that's already been submitted. Pass criterion: the FLW understands why the submission was rejected and what to do next.
longitudinal-visits
The PDD describes repeat visits to a durable entity over time.
Generate 4–6 DELIVER-SIDE journeys. The mandatory Learn smoke from
Coverage rule 4 is ADDITIONAL to this count — a two-app opp therefore emits
5–7 journeys in total. See § How to read a branch count. Keep visit-flow and
data-quality-error from atomic-visit, and add the journeys that only exist
once there is a case:
- case-selection — the FLW opens the Deliver app, finds the right entity in the case list (search / filter), and sees enough state on the case tile to know which visit is due. Pass criterion: the FLW can tell which visit is next without asking anyone.
- followup-with-preload — a follow-up visit against an existing case. Pass criterion: prior state visibly preloads, and the FLW is not re-keying what the case already knows.
- repeat-activity — the FLW submits an activity this entity has
already had. Pass criterion: the app or the payment model handles it
per
payability-against-history, and the FLW is not misled into expecting payment for work that will dedup away. - registration — only when the entity is registered in-app (skip when cases arrive by import or already exist).
focus-group
The PDD describes FLW-facilitated group discussions where qualitative
content is captured in a Google Doc out-of-band. The mobile-app
surface is narrow: one ~5-field attestation form (consent, date,
venue, GPS, photo) submitted at session end as the payment trigger.
The gdoc is written separately, hours-to-days later, with no
gdoc_link field on the form. See
docs/superpowers/specs/2026-05-15-focus-group-archetype-redefinition.md.
Generate 2–4 DELIVER-SIDE journeys covering the categories below. There is
no Learn app for focus-group, so Coverage rule 4 adds nothing here and
this count is also the total. See § How to read a branch count.
- session-setup — the FLW arrives at the venue, runs through the consent step verbally with participants per the consent script (out-of-app), and is ready to facilitate. No in-app interaction at session start — the mobile form is filled at session end. Happy path: arrives prepared, consent obtained, ready to begin.
- recruitment-failure — the FLW arrives and turnout is below the PDD's minimum group size. Pass criterion: the FLW knows the protocol (cancel / reschedule / proceed-with-fewer per the LLO coordinator's guidance — typically reschedule). App-side: if the session doesn't run, no attestation is submitted (no payment).
- consent-handling — one or more participants decline to
participate. Pass criterion: the FLW captures the refusal verbally,
knows whether to proceed (per consent script: proceed only if all
remaining participants consented), and if proceeding, the
attestation form's
consent_all_participantsfield can answeryesfor the participants who DID consent and stayed. If consent fails the session aborts; no attestation submitted. - attestation-submission — the FLW reaches session end, opens the
Deliver app, fills the 5-field attestation form (consent, date,
venue, GPS, photo), and submits. Pass criterion: form submits
cleanly within the 24h window; GPS captured at venue; photo not
showing faces; coordinator can match this attestation to the gdoc
the FLW will write later by
(FLW, session_date, venue). Edge cases: GPS out of expected radius, late submission (>24h).
multi-stage
The PDD has two or more sequenced stages with different archetypes.
For each stage, identify its declared archetype and generate that
archetype's full journey list from the sections above. Prefix each
journey title with the stage number (e.g. Stage 1 — session-setup,
Stage 2 — visit-flow).
Generating per-stage journeys: treat each stage independently. A
focus-group Stage 1 generates the 4 focus-group journeys; an
atomic-visit Stage 2 generates the 4 atomic-visit journeys. Do not
collapse stages or skip journeys because they seem similar across
stages — the FLW needs clear per-stage UX flows.
Cross-stage journey (always add, once per PDD, not per stage):
- stage-transition — the FLW finishes Stage 1 and begins Stage 2.
Happy path: the FLW knows from the app that Stage 1 is closed,
understands what changed in their available actions, and can begin
Stage 2 deliveries without confusion. Edge case (
error_recoveryflavor): an FLW attempts a Stage-1-only action after the gate has closed; the app makes the new constraint legible. If the PDD's Stage Gate section is missing or vague, flag it as a[WARN]in the coverage self-check (step 5) — without a clear gate the deep eval can't grade transition correctness.
Coverage rules
Before writing the file, verify:
One journey per archetype-branch category — when the PDD declares the underlying surface. Atomic-visit's expected categories are visit-flow, eligibility-edge, data-quality-error, duplicate-handling. Emit a journey for every category whose surface the PDD declares; SKIP categories where the PDD explicitly defers the surface (eligibility rules deferred → no eligibility-edge journey; no photo or GPS → no photo-quality data-quality-error journey). Mark each skipped category with
[INFO]calibration context in the coverage self-check at the bottom of the doc; the eval-side rubric grants a PDD-deferral exemption for these. Focus-group needs session-setup, recruitment-failure, consent-handling, attestation-submission (same PDD-deferral rule). Multi-stage needs per-stage coverage plus the stage-transition journey. Minimum after deferral exemptions: visit-flow (or per-archetype equivalent) is ALWAYS required.At least one
error_recovery-flavored edge case per journey. Theapp-ux-evaldeep rubric specifically grades whether the app makes failure modes legible and recoverable; a journey with no error-recovery edge case starves that rubric of signal. Examples: "FLW recovers from a network drop mid-submit and doesn't lose form state," "FLW hits a validation error and understands which field needs fixing," "FLW understands why a duplicate was rejected and how to proceed."At least one measurable pass criterion per journey. "Journey completes" alone is not measurable; pair it with a time bound, a recoverability claim, or a structural-output claim that the deep eval can grade.
Training-app coverage (Learn smoke) — REQUIRED for every PDD with a Learn app. Every archetype except a hypothetical Learn-less mode produces a Learn (training) app. Phase 6's training deck needs screenshots of BOTH apps, so the journey set MUST include at least one Learn-app journey:
training-completion-smoke— happy-path FLW completes Learn Module 1 (content form + assessment), passes the assessment, returns to the suite root with Module 1 marked complete. Pass criterion: the FLW reaches the first assessment, submits with a passing score, and Module 1 row shows a completion indicator (per atlas § 6 — completion-state is rendered on the row).Set
app: learnandis_smoke: trueon this journey. It is the mandatory pair to the Deliver-side smoke for two-app opps.
Deeper Learn-app journeys (full curriculum walk, assessment-fail recovery, etc.) belong in
/ace:qa-deepand may be added as non-smoke entries withis_smoke: false. Phase 6 shallow only needs the one smoke per app.This rule was added 2026-05-18 after the malaria-itn-app run 20260517-1829 surfaced a Phase 6 halt: Phase 2 had generated 9 Deliver journeys + 0 Learn journeys, Phase 3 dutifully wrote
smoke_journeys_per_app: {learn: 0, deliver: 1}, and Phase 6's smoke run tried to reach Deliver viaconnect-claim + Start + tap V1— which lands in Learn, not Deliver, because Connect gates Deliver behind Learn-assessment completion (seedocs/learnings/2026-05-18-connect-gates-deliver-on-learn-completion.md). The right fix is structural: always emit the Learn smoke so Phase 6 captures it independently, AND the Deliver smoke walks Learn to completion first (seeapp-test-casesfor the recipe shape).
If any rule is missed, return to the journey-generation step (step 4
in ## Process) and add until coverage is satisfied.
The numbered rules above are blocking — failing any of them sends you
back to regenerate journeys. The [WARN] cases listed in ## Failure Modes (e.g., a vague Stage Gate) are non-blocking — flag them in the
output but proceed.
MCP Tools Used
- Google Drive:
drive_read_file,drive_create_file
Mode Behavior
- Auto: Generate the full journey file, self-evaluate coverage, write it.
- Review: Pause before writing to present the generated journey list for operator approval. This artifact is the UX ground truth for downstream app QA, so getting it wrong cascades into false-positive / false-negative deep-eval failures in Phase 6.
Dry-Run Behavior
When --dry-run is active:
- Generate the journey file content as normal.
- Write to
comms-log/dry-run-pdd-to-app-journeys.mdinstead of2-scenarios/pdd-to-app-journeys.md. - State tracks as
dry-run-success.
Failure Modes
- PDD missing or empty — blocker; Phase 1 Step 1 (
idea-to-pdd) hasn't completed. Don't synthesize; escalate. - PDD has neither "FLW Requirements" nor "Target FLW" section —
blocker; the journeys describe what the FLW does and need a defined
FLW. The canonical name is "FLW Requirements" (per
templates/pdd-template.md); "Target FLW" is the legacy name and is also accepted. Flag back to the operator and request a PDD revision; don't synthesize a persona. - PDD has no eligibility / duplicate-handling / consent / output
spec — for the relevant archetype, the journey set will be
missing a category. Flag a
[WARN]rather than blocking, and note in the journey file which categories were skipped because the PDD was thin. The deep eval needs to know to expect partial coverage. - Multi-stage PDD with vague Stage Gate — the
stage-transitionjourney can't grade transition correctness if the gate isn't defined. Flag a[WARN]and write the journey with the best-available constraints; recommend the operator strengthen the Stage Gate section before activation.
Change Log
| Date | Change | Author |
|---|---|---|
| 2026-05-08 | No QA companion. pdd-to-app-journeys-qa removed (PR #160) — downstream consumers are LLM-driven; structural label-format checks gate nothing real, and the eval already covers the substantive concerns. See skills/_qa-decisions.md for the registry entry + revisit conditions, and docs/learnings/2026-05-08-fake-qa-detection.md for the heuristic. |
ACE team |
| 2026-05-15 | Accept either "FLW Requirements" (canonical, per templates/pdd-template.md) or "Target FLW" (legacy) as the persona section in Process step 3 + Failure Modes. Prompted by malaria-itn-fgd/20260514-2007 where the template-conformant PDD said "FLW Requirements" and the skill halted looking for "Target FLW". See jjackson/ace#302. |
ACE team |
| 2026-05-15 | Recharacterize focus-group journey categories for the attestation-form-only shape (PRs #305, #306): output-coherence (which assumed the FLW fills 28 in-app fields with content) → attestation-submission (FLW fills the 5-field form at session end, no per-section content in the app). Session-setup reframed to note "no in-app interaction at session start" — the mobile form is end-of-session only. Other categories (recruitment-failure, consent-handling) reframed to note no-attestation-on-abort semantics. Coverage rule updated to reference the new category name. Prompted by malaria-itn-fgd/20260514-2352 re-run. |
ACE team |
| 2026-05-29 | Deployability-exercising journeys (ITN post-mortem, producer↔eval symmetry). Added Step 4a + two coverage rules: when the Evidence Model implies it, the journey set MUST include ≥1 negative-path/bad-input journey (the recoverable-rejection path that app-test-cases turns into a negative-path recipe and app-ux-eval § capture_robustness grades), capture-fidelity pass criteria (GPS accuracy gating, structured-pick over typing, other→specify), and — for multi-visit designs — a persistence journey (follow-up records change). Symmetric with the new pdd-to-app-journeys-eval § deployability_fitness hard-gate; PDD silence is not a waiver. See docs/superpowers/specs/2026-05-29-eval-fitness-gap.md. |
ACE team |
| 2026-09-06 | A low-accuracy GPS fix is no longer offered as a negative-path example, and the capture-fidelity example no longer says "rejected" (dimagi-internal/ace#1619). The bad-input bullet listed "a low-accuracy GPS fix where a radius is specified" beside blank/out-of-range/malformed-phone, and the capture-fidelity bullet modelled the expectation as "GPS capture is rejected below the accuracy threshold." No build can do either: Nova rejects validate on kind: geopoint and Connect's verification-flags form no longer carries gps / gps_radius_meters (ace#1006, ace#1013), and idea-to-pdd § Step 4a FORBIDS the PDD from asserting it. So this skill was handing authors the exact phrasing Phase 1 is not allowed to write, app-test-cases then compiled it into a negative-path Maestro recipe that cannot pass, and pdd-to-app-journeys-eval graded the result against it. Both examples now model the observability contract (accuracy shown + submitted + a whole-range advisory), and the bullet points at _app-component-library.md § Mechanisms a PDD must not assert — the pointer test/skills/pdd-must-not-assert-mechanisms.test.ts already required of idea-to-pdd and its eval, and never of this pair. Sibling half of the same drift in pdd-to-app-journeys-eval; pdd-to-deliver-app-eval § Capture fitness received this correction on 2026-07-28 and it was not propagated here. |
ACE team |
| 2026-09-08 | Every archetype branch's journey COUNT was smaller than the file's own blocking coverage rules mandate (dimagi-internal/ace#2274). longitudinal-visits declared 3–5 against a compliant floor of 6 and atomic-visit declared 2–4 against 5, because Coverage rule 4 (2026-05-18) made a Learn smoke journey mandatory and no branch count moved with it — so both ranges were unsatisfiable while complying with the same file's blocking rules, and every longitudinal and atomic run paid the reconciliation. Counts are now explicitly DELIVER-SIDE with the Learn smoke stated as additive, longitudinal-visits is 4–6 so the conditional registration journey fits, and a new § How to read a branch count records the derivation. Third instance of the count-drifts-behind-the-mandate class in this file family after ace#1545. Observed on bednet-check-2-visit/20260908-1544, where the compliant set was 7 journeys against a declared ceiling of 5. Enforced: test/skills/journey-count-consistency.test.ts (ratchet with controls — the ceiling must cover the branch's own bullets plus any it keeps from another branch). |
ACE team |