journey-mapper
Skill1 starsChanged yesterdayMITView on GitHub
Map the user journeys of an application by reading its codebase (web, mobile and API), and write them as prioritised, evidence-linked Journey Markdown files ready to be turned into automated tests. Accounts for every route, screen, endpoint, entry point and goal event it finds, reports coverage honestly, and never presents behaviour inferred from code as intended behaviour.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- joeyvansommeren/journey-mappertheir own version, first seen Oct 12, 2026
- stritar/skillstheir own version, first seen Sep 11, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- joeyvansommeren/journey-mapper★ 90same name
- stritar/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository33 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- api-contract-testerSkill
- bug-reproducerSkill
- ci-failure-triagerSkill
- ci-suite-runnerSkill
- code-security-auditorSkill
- cross-browser-checkerSkill
- db-migration-reviewerSkill
- dead-test-finderSkill
- exploratory-charter-writerSkill
- flaky-test-hunterSkill
- hypercare-anomaly-watcherSkill
- i18n-checkerSkill
- journey-to-testsSkill
- mobile-app-auditorSkill
- mutation-testerSkill
- performance-budget-auditorSkill
- post-deploy-validatorSkill
- privacy-flow-auditorSkill
- qa-orchestratorSkill
- release-readiness-gateSkill
- requirements-traceability-auditorSkill
- resilience-proberSkill
- risk-based-test-plannerSkill
- test-case-designerSkill
- test-data-auditorSkill
- test-impact-selectorSkill
- test-suite-evaluatorSkill
- ticket-readiness-reviewerSkill
- ticket-to-tddSkill
- ui-crash-hunterSkill
- visual-regression-reviewerSkill
- wcag-auditorSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 8 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Coverage is reported as a lower bound: Never claim to have documented "the entire application" without the coverage numbers.
- Very specific: line 45
Read-only: Don't modify application source, run migrations, or call external services.
- Distinctive: line 48
Don't reveal secrets: If you encounter credentials while reading code, don't copy them into journeys, test data or evidence notes.
- Distinctive: line 64
If the user names a domain or feature, map that domain thoroughly rather than the whole application thinly.
- Very specific: line 107
Multi-service backends: when endpoints come from several apps or services in one repository, the extractor labels each item with service …
- Very specific: line 112
Existing journeys: if the output directory already exists, read index.md and note which journeys are reviewed or approved.
- Very specific: line 252
Read the limitations the extractor reports, and carry any that apply into metadata.notes.
- Distinctive: line 303
A separate journey: when the goal differs, the persona differs and the flow differs materially, or the variant would need more than about 3 …
- Very specific: line 320
Use context.tests from the extractor (visited URLs), plus your own reading of the e2e and UI test suites.
- Distinctive: line 342
Every surface item must end up in exactly one bucket:
- Very specific: line 375
Write journey_map.json into the output directory (journeys/journey_map.json), conforming to schemas/journey_map.schema.json.
- Distinctive: line 431
Keep it short. Include:
- Distinctive: line 444
Use direct language such as:
- Distinctive: line 453
Don't describe the map as complete, comprehensive or exhaustive.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Journey Mapper
Mission
Produce an inventory of the user journeys in a piece of software, derived from its source code, that a QA engineer can review and then turn into tests.
A journey is how one persona reaches one goal: an ordered set of user actions, each with an observable expected outcome, plus its significant variants (error paths, alternative paths, role or platform differences).
The output is:
- One Journey Markdown file per journey (format:
JOURNEY_FORMAT.md). index.md: journeys by domain, priority, persona and automation status, with flow diagrams.coverage.md: every surface item found, and which journey covers it (or why none does).journey_map.json: the machine-readable result, conforming toschemas/journey_map.schema.json.
The Journey to Tests skill consumes these files, so their accuracy matters more than their number.
Non-negotiable rules
- Inferred is not intended. Journeys derived from code describe how the software behaves
today, which may include bugs. Always emit
status: inferred. Only a person promotes a journey toreviewedorapproved. Behaviour that looks unintended goes inopen_questions; never silently "correct" it in the steps. - Every step cites code evidence (
fileandline) showing where the action is handled or the outcome is produced. If you can't find evidence for a step, don't write the step. Record the gap as an open question. - Every surface item is accounted for. Each route, screen, endpoint, entry point and goal is either covered by a journey, listed as an orphan with a reason, or listed as unreachable with evidence. The validator enforces this arithmetic.
- Coverage is reported as a lower bound. Never claim to have documented "the entire application" without the coverage numbers. Dynamically built routes, server-driven UI and remote configuration can hide surface that static analysis can't see; state this.
- Expectations must be observable by a user or a test: text, navigation, enabled state, a visible error. "State is updated" is not an expectation; "Cart badge shows 1" is.
- Read-only. Don't modify application source, run migrations, or call external services.
The only files you write are under the output directory (default
journeys/). Leave them uncommitted. - Don't reveal secrets. If you encounter credentials while reading code, don't copy them into journeys, test data or evidence notes; refer to the file location and secret type only.
- Never overwrite human decisions.
write_journeys.pypreservesreviewed/approvedfiles and## Notessections; never bypass it by writing journey files directly.
Inputs
| Input | Default | Notes |
| Repository | current directory | Monorepos are supported |
| Domains | all | Restrict a run to some domains, e.g. checkout, account |
| Max journeys per run | 50 | Large applications are mapped over several runs |
| Platforms | detected | web, ios, android, desktop, api, cli |
| Output directory | journeys/ | |
| Diagrams | on | Mermaid flowchart per domain in index.md |
If the user names a domain or feature, map that domain thoroughly rather than the whole application thinly.
Step 1: Recon
Establish, citing files:
- Application type(s): web SPA, SSR web, native or cross-platform mobile, desktop, API-only, CLI. A repository may contain several apps; treat each as a platform of the same product only if they share a backend and user accounts.
- Frameworks and routing: Next.js, Nuxt, SvelteKit, Remix, React Router, Vue Router, Angular, Expo Router, React Navigation, Flutter (GoRouter/Navigator), Android (Navigation, Compose, activities), iOS (SwiftUI, UIKit, storyboards); backend frameworks.
- Role model: how users are identified and what roles or permissions exist (e.g. guest,
member, admin, tenant owner). These become personas. Role or group names often encode several
dimensions, e.g.
<app>-<env>-<region>-<site>-<READ|WRITE>such asbakery-prod-north-harbour-write, with a special site value that grants every site. Split them: the access level gives the personas (READ is a viewer, WRITE an editor), and the other dimensions become preconditions ("signed in as an editor of one site") and variants (one site versus every site), not one persona per combination. Check whether every screen honours the access level: a write action that a read-only user can still reach is an open question. - Feature flags: the flag system and where defaults are defined.
- Domains: functional areas, from directory structure (
features/checkout), route prefixes and navigation menus. Use lowercase slugs. - Existing end-to-end and UI tests: frameworks and locations. Note helper modules
(
e2e/helpers.ts) whose functions run whole flows for the specs that call them. - Next.js App Router: the guard file is
middleware.ts, orproxy.tsfrom Next 16, at the project root or insrc/. Layouts (layout.tsx) often hold auth checks for every page below them. Server components may read the database directly, which is where ownership checks belong. Server actions ('use server') are endpoints. Imports go throughtsconfig.jsonpathsaliases such as@/*. - React Router (or Vue Router, Angular) single-page app: routes are usually one
createBrowserRouter([...])config or<Routes>inApp.tsx, with feature modules that render their own<Routes>under a splat route (path: 'shop/*'). Guards are wrapper components (<ProtectedRoute>, a layout that redirects to sign-in) rather than middleware; check whether the sign-in redirect keeps the page the user asked for. API calls go through a client module (api/*.ts, generated clients, React Query hooks), so trace each screen's calls to that module and from there to the endpoint. - Several repositories (an SPA and a separate API repository, or several services): put
them side by side under one parent directory, run the extractor on each, and cite evidence as
<repo>/<path>relative to that parent. Validate with--repo <parent>, so one run re-reads citations in every repository. Merge the surfaces into one map, prefixing each item'sfilewith its repository directory. - Multi-service backends: when endpoints come from several apps or services in one
repository, the extractor labels each item with
service(from the nearest project manifest, e.g.services/<name>/pyproject.toml) and starts its proposed domain with it (orders-loaves). The same path in two services is two items; name the service in the journey's steps (POST /v1/loaves on the orders service). - Existing journeys: if the output directory already exists, read
index.mdand note which journeys arereviewedorapproved.
Step 2: Extract the surface
Run the extractor:
python scripts/extract_surface.py <repo> --out surface.jsonIt finds candidate routes, screens, API endpoints, entry points (deep links, URL schemes) and
goal events (analytics calls). Write surface.json to a scratch location, not into the
repository. Details worth knowing:
- Endpoints are per HTTP method. A Next.js
route.tsthat exportsGET,PATCHandDELETEgives three items (GET /api/x/:id, ...), each at its export line.ANY /pathmeans no exported method was found; check how the file exports its handlers. Server actions appear asACTION <function name>. - Intercepting routes (
(.)x,(..)x,(...)x) are reported under the route they intercept, with detectornext-intercepting-routeand a note. They are a second way to render that route (usually a modal on client-side navigation), so cover them with a variant. - Next.js file conventions are read with the shared Next.js reader. Metadata routes
(
robots.ts,sitemap.ts,manifest.ts,favicon.ico,icon,apple-icon,opengraph-image,twitter-image) areGETendpoints with detectornext-metadata-routeand domainsite-files; an Open Graph or Twitter image is added to the page metadata of its segment automatically, so a sharing-preview journey reads it from the page head (a note says so). A page or route handler with segment config carriessegment_configand a note:generateStaticParamswithdynamicParams = falsemeans only the generated values are pages and any other value answers 404, a variant every journey through that route needs;export const dynamic/revalidatesay when content changes. A route with no static segment (/:slug) gets a domain from its page component (SightingPagebecomessighting) or a telling parameter name, with a note that it was guessed.context.route_stateslistsnot-found,error,loading(andtemplate,default,global-error,forbidden,unauthorized) files per segment: the 404, error and loading variants.context.third_party_scriptslistsnext/scriptand<script>loaders and connection hints to other hosts (withstrategyand line); a limitation says when an analytics loader is present but no goal event was found (page views only: ask which outcomes matter, don't invent goals).context.service_workerslists each worker, its registration and fetch strategies, andcontext.public_filesthe non-media files served frompublic/(/manifest.json,/ads.txt, verification files). A journey whose run depends on a third party or the worker names it as a precondition; tests written from the journeys block both by default. - Goals include calls to tracking wrappers: functions that forward their first parameter to a
known analytics call (e.g.
trackMixpanelEvent('sign_up_completed')), found automatically and listed incontext.goal_wrapperswith where they are defined. If the app tracks through a wrapper the extractor misses, rerun with--goal-wrapper <name>(repeatable). Events passed as constants (EVENTS.SIGNUP) are not resolved; add them as agent items. - Python routes (Flask, FastAPI, Azure Functions) are read by parsing the code, so
decorators in docstrings and usage examples never count. FastAPI paths include the
APIRouter(prefix=...)(also on subclasses ofAPIRouter) and everyinclude_router(..., prefix=...)above it; Flask paths include the blueprint'surl_prefix. A note says when a router was never seen being included (a prefix may be missing) or when part of a path is computed.context.python_mountslists includes through variables or loops. - Server-rendered pages (Flask): a view whose function calls
render_template(...)is a web route (detectorflask-view) with itsmethods,viewand thetemplateit renders, not an API endpoint; JSON views stay endpoints.context.templateslists every server-side template (.htmlunder atemplates/directory,.jinja,.j2) with the routes that render it, its links (href="/..."andurl_for('view'), resolved to paths), forms (action, method),fetch()calls and the templates it extends or includes, each by line: these are the navigation and API-call edges for Step 3. Django views and computed template names are not followed; trace them by hand. A FastAPI handler that returns an HTML page (HTMLResponse, atext/htmlmedia type, an.htmlfile) is a web route too (detectorfastapi-view). - Plain static front ends (no framework): every
.htmlpage outsidetemplates/is a route (detectorstatic-html), at the path it is served from (under aStaticFilesmount of its directory, or relative to the topmost folder holding anindex.html).context.static_pageslists each page's buttons, inputs, forms, links, scripts and thefetch()calls of its scripts, by line; URL parameters its scripts read (new URLSearchParams(location.search).get('lang')) are entry points (query: ?lang), andlocalStorage.setItem('key', ...)writes are low-confidence goals (detectorlocal-storage). Click handlers are not traced: follow them from the button ids into the scripts by hand. - Static mounts, conditions and middleware:
app.mount("/", StaticFiles(directory="dist"))is a route (/{path:path}, detectorstarlette-static, with thedirectoryit serves). A route whose router is included, or a mount added, under anif(if args.uploads: app.include_router(...)) carries the test ascondition: it exists in one serving mode only, which a journey must say.app.add_middleware(...)and@app.middleware("http")are listed incontext.guards(kindmiddleware, with anycondition). - PHP front controllers are read by pattern only (
preg_matchand comparisons onREQUEST_URI) as low-confidence endpoints, and a limitation names the PHP files; other PHP routing is not read, so map it by hand. - Build-output folders:
dist/,build/andout/are skipped only when something in the repository produces them (a package.json build script, a bundler config, a.gitignoreentry); they are listed instats.skipped_build_dirswith their file count and named on stderr, and--include DIRreads one. A committed folder nothing produces is a hand-written front end and is read (stats.source_build_dirs). - Client-side routes (React Router, Vue Router, Angular) are joined to their parents:
childrenarrays, nested<Route>elements, and a component's own<Routes>mounted by a splat route in another file (/shop/*rendering<ShopModule/>makes itscakesroute/shop/cakes). Paths built from constant objects (ROUTES.LOGIN,`${ROUTES.SHOP}/*`) are resolved. Index routes carryindex: trueand render at the parent's path; lazy routes and redirects say so in a note. A path that could not be resolved keeps its expression in braces. - Entry points include command-line commands (
cli: <program> <command>from argparse sub-commands, click and typer commands,[project.scripts]andpackage.jsonbin; a flags-only argparse program is onecli: <program>with itsoptions, and a hand-writtencommand = sys.argv[1]; if command == "pack":dispatch givescli: <program> pack) and Azure Functions triggers (blob trigger: <path>,timer trigger: <schedule>). A trigger is not user-facing by itself: find the user action that causes it (an upload that writes the blob), cover it from that journey, or orphan it asnot_user_facing. Operator command lines are journeys for an operator persona when they change what users see; when a server's flags select serving modes, "start the server in mode X" is such a journey, and the routes and middleware whoseconditionnames that flag belong to it. - Domains on routes and endpoints are proposals from the first path segment (
/api/orders/:idbecomesorders), prefixed with the service in multi-service repositories. In an app that serves pages and a JSON API under/api/, the API's endpoints share the domainapi; files served at the site root (/robots.txt,/sitemap.xml) getsite-files. Correct them during review: they decide whatout_of_scopemay hold. - Data directories are not walked. JSON files are opened only by name (
package.json,host.json,function.json,tsconfig/jsconfig,openapi*/swagger*), and a directory holding 200 or more files, at least 90% of them data files (JSON, CSV, XML, YAML, ...) and none code, is skipped and listed instats.skipped_data_dirs. Pass--exclude <dir>(repeatable) to skip any other directory. - Success messages (
toast.success('Order placed'),setSuccessMessage(...)) are reported as low-confidence goals with detectorsuccess-message. Confirm each marks completion. - Test-only surface (
/test-support/..., Sentry example pages) carries a note. Confirm it, then orphan it asnot_user_facing. - Context:
flags,tests(test files and the URLs they visit, bykind:browserfor Playwright, Cypress, WebdriverIO, Selenium and Python Playwright tests;http-clientfor tests that request a URL through a framework test client, such as Flask'sclient.get('/x')or supertest, and assert the response),unit_tests(how many unit and component test files and cases exist, and their runners: not journey tests, so they never make a journeyautomated),services,guards(each Next.jsmiddleware.ts/proxy.ts: itsmatchervalues, lists of path prefixes such asAUTH_REQUIRED, path checks and redirects, by line),layouts(each App Router layout with lines that look like guards),path_aliases(tsconfig/jsconfigpaths),goal_wrappers, and for Next.jsroute_states,third_party_scripts,service_workersandpublic_files(above).
The extractor is heuristic. Then:
- Verify each item. Remove false positives, e.g. a
HomeScreenclass that is a component, or apath:key that isn't a route. Record removed items as orphans with reasonfalse_positiveinstead of deleting them, so the numbers stay honest. - Resolve nested and relative routes into full paths where you can.
- Add items the extractor can't see, with
"source": "agent", a file and line, and the next free ID in that kind's sequence (R-,S-,E-,N-,G-). Typical additions:- Expo/React Native linking config in
app.json - routes built at runtime (from data or a loop)
- push-notification handlers
- links in email templates
- server-rendered pages in templating languages
- command lines the extractor doesn't recognise (hand-parsed
sys.argv, shell scripts)
- Expo/React Native linking config in
- Read the
limitationsthe extractor reports, and carry any that apply intometadata.notes.
Step 3: Build the interaction graph
Trace how users move between surface items. For each screen or route, read its handlers and record:
- Edges: user actions that navigate or change state (
router.push,navigate(),<Link>, form submits that redirect,Navigator.push, segues). - Guards: authentication checks, role checks, feature flags, and required state (e.g. cart not
empty) that must hold for an edge to be available. Start from
context.guardsandcontext.layouts: a matcher says which requests reach the guard file, the path lists and checks say what it enforces, and the redirects show where a refused user goes (check whether the redirect keeps the query string). Confirm each one by reading the lines cited. - API calls each action makes, linking UI to endpoints. Name the method and path
(
POST /api/orders) so the call resolves to one endpoint item. Follow imports throughcontext.path_aliases(e.g.@/lib/xissrc/lib/x).
Record nodes (entry, screen, state, goal) and edges in the graph section of the map.
The graph doesn't need every edge in the application. It needs the edges that the journeys
traverse, plus the edges that make the reachability conclusions in Step 8 defensible. If you
don't build it, set graph_declined to the reason instead; the validator requires one or the
other, and journey-graph.json and the diagrams are then not written.
Step 4: Identify goals
Goals are states a user is trying to reach. Sources, strongest first:
- Analytics events that mark completion:
order_completed,signup_completed,report_exported. - Success screens, confirmation routes and success toasts.
- Transitions to terminal or meaningful statuses in state machines (e.g.
status = 'submitted'). - Created, updated, deleted or exported resources reached through the UI.
Navigation events alone (page_viewed) are not goals. When the extractor reports view or
progress events (checkout_started, dashboard_viewed), keep them in the surface: cover them
from the journey whose step fires them, or orphan them with the reason that applies. Don't drop
them, or the coverage arithmetic stops describing the code.
Step 5: Synthesise journeys
Walk the graph from entry points to goals. Follow RUBRIC.md for granularity:
- One journey per persona-goal pair. Name it by the outcome: "Guest completes checkout with card", not "Checkout page".
- Steps are user actions, typically 3–12. Don't describe internal calls as steps; cite them as evidence.
- Variants, not new journeys, for error paths, validation failures, alternative entry points (deep links), role differences in the same flow, and platform differences. Each variant branches from a numbered step.
- A separate journey when the goal differs, the persona differs and the flow differs materially, or the variant would need more than about 3 steps of its own.
- Preconditions state the data and session state needed, e.g. "a product with stock > 0", "signed in as member".
- Test data names the kind of data needed and where it comes from (seed scripts, sandbox cards, fixtures). Never paste secrets.
- Not automatable lists expectations a test can't check reliably, with a reason. Keep this short and honest.
- Platforms: list every platform where the journey exists, and use variants for meaningful platform differences.
Assign IDs JRN-<DOMAIN>-<NNN>, where DOMAIN is a short uppercase code for the domain (e.g.
CHK for checkout). If a journey already exists in the output directory, reuse its ID. IDs
are never reassigned to a different journey.
Step 6: Match existing tests
Use context.tests from the extractor (visited URLs), plus your own reading of the e2e and UI
test suites. A http-client test exercises a page or endpoint at the HTTP level: it can make a
journey partial, never automated (RUBRIC section 6). Match tests to journeys by route, screen, selectors, API calls and test titles. Set:
automated: existing tests exercise every step and assert every Expect of the main path.partial: some steps or variants are exercised, or steps run without their outcomes being asserted.none: no test exercises the journey.
List matched test files in tests. Never set partial or automated without listing the tests.
Be conservative: a test that visits a page isn't a test of the journey. A URL wait
(waitForURL, toHaveURL) asserts only a navigation Expect, not what the page shows. Flows run
in helper functions count for the spec that calls them: list the spec, and read the helper to see
what it asserts (RUBRIC.md section 6).
Step 7: Prioritise
Apply the priority model in RUBRIC.md and write a one-line priority_reason for every journey.
Untested P1 journeys are the headline finding of the report.
Step 8: Account for every surface item
Every surface item must end up in exactly one bucket:
| Bucket | When |
| Covered | Listed in at least one journey's covers |
Orphan no_user_path_found | User-facing, but you couldn't trace a path to it |
Orphan not_user_facing | Health checks, webhooks, internal or machine-to-machine endpoints |
Orphan out_of_scope | Belongs to a domain excluded from this run. The item's domain (or the orphan's own domain, when the item's proposed one is wrong) must be outside run_scope.domains |
Orphan not_mapped_this_run | In scope, and you found its user path, but didn't map it in this run. The note names the path (file and line) |
Orphan needs_review | Ambiguous; a person must decide (explain in note) |
Orphan false_positive | Extractor output that isn't actually a route, screen or event |
Unreachable dead | No navigation, link, redirect or call reaches it (cite the evidence of absence you checked) |
Unreachable flag_off | Only reachable behind a flag that is off by default everywhere (cite the flag default) |
Unreachable guarded_unreachable | Behind a guard no real user can satisfy |
A journey whose subject is a cross-cutting guard (an authentication middleware in
context.guards) rather than a route may have empty covers with a covers_reason saying so; do
not pad it with routes it does not reach.
Observed is not inferred. expect is what the code implies. When you ran the app (a loopback
probe, a browser capture), record what it showed on the step as observed: {"result", "run", "at"}:
run is the run's evidence file, relative to the map's directory (keep it under the output
directory, e.g. journeys/run/probe/home.txt is run/probe/home.txt), and at is when it ran. The
validator checks all three are there and that the run file exists. write_journeys.py writes each
observation as the step's own indented line after its Expect (**Observed:** <result> (run
`<run>`, <at>), Journey Markdown 1.1), never into the Expect, and render_report.py lists
observed steps apart from the inferred ones.
Admin-only and internal-tool paths are not unreachable. Map them as journeys with the right persona.
Step 9: Write and validate the journey map
Write journey_map.json into the output directory (journeys/journey_map.json), conforming to
schemas/journey_map.schema.json. Set metadata.run_scope.domains to "all" or the list of
domains mapped. Then:
python scripts/validate_journey_map.py journeys/journey_map.json --repo <repo>With --repo the validator re-reads every cited file and line: a missing file, a line past the
end of the file, or a blank line cited as step evidence is an error. If an evidence entry has an
excerpt, it must be on the cited line. It also checks that each journey's tests exist. It
checks, with or without --repo, that journeys and not_mapped_this_run orphans are inside the
run scope and out_of_scope orphans are outside it, and that the graph is present or declined.
It also warns when a journey covers an item whose file none of the journey's evidence cites
(padded coverage: cite the line where the journey reaches the item, or drop it from covers),
and when a map-level open question repeats a journey's. Map-level open_questions are for
questions that span journeys; a question about one journey goes in that journey only. Run with
--strict to make the warnings errors, and fix them before handing the map over.
Fix every reported problem. Don't fudge the coverage numbers to pass: if an item isn't covered, list it as an orphan or unreachable item with a truthful reason.
Step 10: Write the journey files
python scripts/write_journeys.py journeys/journey_map.json --out journeysThis creates or updates the journey files by ID, regenerates index.md, coverage.md and
journey-graph.json, and records what it did in the map's files list. It never overwrites a
reviewed or approved journey (it writes <name>.proposed.md beside it). It preserves
## Notes, merges tests, and never deletes files: journeys no longer found are reported as
stale. Use --dry-run to preview.
Step 11: Lint and report
python scripts/journey_md.py lint journeys --strict
python scripts/render_report.py journeys/journey_map.jsonStrict lint must pass. Use --color never when the output will be pasted elsewhere, and
--brief for the headline only. In a scoped run the coverage headline counts the run's domains
(every item except out_of_scope orphans), and the whole-repository figure follows it.
Large applications
Map one or a few domains per run, using run_scope.domains. Items in other domains are orphans
with reason out_of_scope; in-scope items you traced but had no time to map are
not_mapped_this_run. Stable IDs make runs add up: index.md always lists every journey
file on disk, and coverage.md describes the latest run's scope. Suggest a domain order to the
user, highest-risk first (payments, authentication, data entry).
Final response to the user
Keep it short. Include:
- Coverage: surface items found, the percentage in journeys, orphans and unreachable items. Say
that it is a lower bound. In a scoped run, give the in-scope figure first and the whole
repository second, and say how many in-scope items were
not_mapped_this_run. - The number of journeys by priority, and the untested P1 journeys by name.
- Behaviour that looked unintended (open questions), with file and line.
- Proposed updates waiting next to reviewed journeys, and stale journeys.
- The next step: a person reviews the
inferredjourneys, then the Journey to Tests skill can turn them into tests.
Required honesty language
Use direct language such as:
- "These journeys were inferred from the code and describe current behaviour; they have not been confirmed against requirements."
- "42 of 57 surface items (74%) are in at least one journey. Routes built at runtime would not be visible to this analysis."
- "No end-to-end test exercises this journey; one test visits the page without asserting the outcome, so automation is marked partial."
Don't describe the map as complete, comprehensive or exhaustive.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

