# Flow Legacy Cross Reference > flow-legacy-cross-reference - Skill: `brite-nites/flow-legacy-cross-reference` (Agent Skill) - Install (CLI): `npx skillmds@latest add brite-nites/flow-legacy-cross-reference` - Raw SKILL.md: https://api.skillmd.com/api/skills/brite-nites/flow-legacy-cross-reference/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Brite-Nites (https://skillmd.com/u/brite-nites) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/brite-nites/flow-legacy-cross-reference --- # flow-legacy-cross-reference Retrofit-only sub-skill. Walks the consumer project's existing Linear milestones, proposes 1-N FDA domain mappings per milestone, lets the user review the proposal in a markdown file, then writes an HTML-comment-bracketed `## FDA migration` appendix to each milestone's description. **This skill MUST NOT be invoked from greenfield.** It satisfies Q9's additive-only contract for retrofits — legacy work stays in its legacy milestones; the appendix is a cross-reference annotation, not a state migration. The dispatching orchestrator (`/flow:retrofit-project` or `/flow:deprecate-legacy`) is responsible for the upstream check; this skill assumes retrofit mode. This skill is **user-invocable** (Q59 amendment lifts the former Q7 model-invocation restriction). Two consumers: `/flow:retrofit-project` (Phase 3 — annotation only per Q9) and `/flow:deprecate-legacy` (Pass 1 — disposition mapping via the 3-tier cascade). The annotation logic (Sections 1-6) is the shared reuse surface; the re-home/close/archive steps in `/flow:deprecate-legacy` are new to that command and NOT part of this skill. The full design rationale lives in `docs/design-rationale/fda-plugin-interview.md` Q14 (memory:94-106) + Q59 (deprecate-legacy scope widening). Q9 (the additive-only lock) and Q22 (milestone schema) are upstream constraints this skill honors. --- ## 1. Mapping determination (Q14.1) --- 3-tier cascade Per legacy milestone, walk three tiers in order. Stop at the first tier producing a confident match. ### Tier 1 --- flow-ID histogram Parse each legacy issue body under the milestone for `\b[A-Z]{2,5}-\d{2,3}\b` flow-ID tokens. Cross-check against `docs/product/master-flow-inventory.md`. Take the top 1-3 domains by frequency. **Threshold:** 0.6 of identified flow IDs must agree on a domain for the tier to "fire". **Degenerate on v1 retrofits** like Brand Hub (no FDA flow-IDs yet exist in legacy bodies). Kept for future-state retrofits where the project has partially adopted FDA before invoking the skill. ### Tier 2 --- title-fuzzy match Levenshtein and token-overlap match the legacy milestone title against the inventory's domain display names. **Threshold:** 0.6 combined score. This is the dominant signal source on most v1 retrofits. ### Tier 3 --- LLM semantic-mapping fallback `Agent(general-purpose, parallel)` over unmatched milestones. Each agent receives the legacy milestone title + description + ~3 child-issue titles. Returns a JSON blob: ```json {"domains": ["AUTH", "TENANCY"], "confidence": 0.75, "rationale": "..."} ``` Or `null` when nothing maps. **Tier 3 is NOT authoritative** --- its output seeds the Q14.6 review doc; the user is the final arbiter. ### Tier 1 read budget (Pass-1 only) Each milestone needs its child-issue bodies parsed for flow-ID tokens. Use **batched `list_issues({milestone: , includeBody: true})`** — one call per milestone — NOT per-child `get_issue` (which would be 5-10x more calls per milestone). 27 milestones * ~500ms ~= ~14s for the read phase, regardless of Tier outcomes. Tier 1 fires its histogram against the returned bodies in-memory; no additional Linear calls. **Filter-reliability caveat.** Per `memory/gotcha_linear_list_issues_milestone_filter.md`, the `list_issues({milestone:})` filter can return cross-milestone bleed-through on some Linear MCP versions. At Pass-1 start, probe one milestone's `list_issues({milestone, includeBody})` and verify all returned issues have the expected `milestone:` field. If bleed-through is detected, fall back to per-child `get_issue` — re-budget Tier 1 at `M_children * ~500ms` ≈ **~67-135s for 27 milestones * 5-10 children**, pushing end-to-end from ~60-70s to ~110-175s. Surface the fallback wall-time bump to the user before continuing. ### Wall-time estimate (Pass-1 mapping only) Theoretical max for the LLM tier = ~27 parallel calls * ~5-10s ~= ~10s assuming unlimited concurrency. Realistic fan-out 6-10 concurrent -> 20-50s for all 27. Most milestones hit Tier 2; Tier 3 realistically fires for 5-10 fall-throughs only --- **~5-15s actual** for Brand-Hub-shaped retrofit, ON TOP of the ~14s Tier 1 read phase above. Re-measure once the skill is built (parking lot). The review-doc's `Source signal` column shows which tier produced each proposal so the user can spot Tier-3 fallbacks first. --- ## 2. Appendix format (Q14.2) HTML-comment-bracketed `## FDA migration` section. Marker pair: ```html ## FDA migration ``` Markers are the idempotency mechanism. Re-runs rewrite content between markers; content outside is never touched. ### Section contents 1. **CDR-023 + operating-standards links** as **absolute GitHub URLs** (`https://github.com/Brite-Nites/handbook/blob/main/...`). Relative paths don't resolve when Linear renders a milestone description in a different repo context. 2. **Coverage table.** Columns: FDA domain -> one-line summary -> Linear milestone link. 3. **Policy (a) callout** --- legacy work proceeds in its legacy milestone; FDA milestones are net-new. 4. `Generated by flow-legacy-cross-reference on ` footer. ### Format gotchas - Numbered/bullet **hybrid** (not pure bullets). Avoids the Linear MCP markdown bullet-truncation gotcha documented in `memory/gotcha_linear_markdown_mangling.md`. - Template includes a `` comment for the future-state when the handbook moves to a public docs site. - **Post-write spot-check.** `get_milestone(id)` after each `save_milestone` to detect Prosemirror mangling (per Q13.5 pattern). On detected drift, log and continue (no auto-retry; Q14.5 governs). --- ## 3. Mutation order (Q14.3) --- preview -> review-doc gate -> execute serial No parallelism. **3 Linear calls per milestone in Pass 2**: pre-write `get_milestone` + `save_milestone` + post-write `get_milestone` spot-check (per Q13.5 pattern in Section 2). 27 milestones * 3 calls * ~500ms ~= **~40.5s for Pass-2 writes**. Each milestone is independent (no chains). Tier 1 reads from Pass-1 (Section 1) are NOT re-fetched. Sequence: 1. Generate the review doc (`docs/plans/-cross-reference.md`). Skill exits. 2. User reviews + edits inline; bumps front-matter `last_reviewed: TBD` to an ISO-8601 date. 3. User re-invokes the orchestrator -> skill detects the date bump -> executes. --- ## 4. Idempotency (Q14.4) --- marker-based; NO scaffold-log analog Pre-write `get_milestone(id)` per legacy milestone: - `` present -> **rewrite content between markers** (replace section). - Markers absent -> **append section** to end of description. **Linear-side state IS the persistence layer.** Unlike `flow-linear-scaffold` (Q13), this skill does NOT write an append-only log under `.flow/scaffold-log/`. 27 milestones * 3 MCP calls * ~500ms ~= ~40.5s overhead is acceptable; the marker contract is the single source of truth. --- ## 5. Failure recovery (Q14.5) --- cadence "log + continue" pattern Each `save_milestone` is independent (no chains; legacy milestones aren't dependency-graph-shaped). On error: - **Transient** (timeout, rate-limit) -> 1 retry + 2s backoff. - **Permanent** (invalid markdown, auth, missing project membership) -> log + continue to next milestone. End-of-run summary surfaces errored rows. User can re-run the skill (idempotent per Section 4) to retry just the failures. NO sub-flow-atomic semantics — independent rows, not a dependency chain. --- ## 6. User-confirmation gate (Q14.6) --- literal markdown review document The gate is a **filesystem artifact**, not a chat ack. ### Two-pass execution **Pass 1 --- generate.** Skill writes `docs/plans/-cross-reference.md`. Front-matter: ```yaml --- generated_by: flow-legacy-cross-reference@ generated_at: last_reviewed: TBD --- ``` Body: a table per legacy milestone (Milestone | Proposed FDA domain(s) | Source signal | Notes) + freeform edit space. Skill exits. **Pass 2 --- execute.** User reviews + edits inline; bumps `last_reviewed:` to an ISO-8601 date. User re-invokes the orchestrator. Skill re-reads the (possibly user-edited) review doc as the **source of truth** for the mapping. If `last_reviewed: TBD` still present, skill refuses to execute with: `"Review doc still has last_reviewed: TBD. Edit docs/plans/-cross-reference.md, bump the date, and re-run."` This makes review completion an **unambiguous filesystem check**, not a chat-ack. The doc is one of the 5 Q10 retrofit gates ("terse cross-reference review document"). It is deletable post-retrofit (a `docs/plans/` artifact). --- ## Worked example Brand Hub retrofit, M=27 legacy milestones: 1. **Pass 1.** Orchestrator dispatches; skill enumerates 27 milestones via `list_milestones`. 2. Tier 1 fires for 0/27 (Brand Hub has no FDA flow-IDs in legacy issue bodies). 3. Tier 2 fires for 22/27 (title-fuzzy hits domain display names cleanly). 4. Tier 3 fires for 5/27 fall-throughs; ~3 agents parallel -> ~10s wall. 5. Skill writes `docs/plans/brand-hub-retrofit-cross-reference.md` with `last_reviewed: TBD`. Exits. 6. User reviews; corrects 2 of the Tier-3 proposals; bumps `last_reviewed: 2026-05-15`. Re-invokes orchestrator. 7. **Pass 2.** Skill re-reads the doc; serially executes 27 milestones with 3 Linear calls each (pre-write `get_milestone` + `save_milestone` + post-write spot-check `get_milestone`) at ~500ms each. Total ~40.5s. 8. 1 milestone hits a transient timeout; retried after 2s + succeeds. 0 permanent failures. 9. Skill exits cleanly with summary: `flow-legacy-cross-reference: 27/27 milestones updated, 1 transient retried, 0 permanent failures.` --- ## See also - `docs/design-rationale/fda-plugin-interview.md` Q14 --- canonical 6-sub-decision spec. - `docs/design-rationale/fda-plugin-interview.md` Q9 --- additive-only retrofit lock. - `docs/design-rationale/fda-plugin-interview.md` Q22 --- milestone schema (Sub-flows table this skill does NOT touch). - `memory/gotcha_linear_markdown_mangling.md` --- Prosemirror mangling patterns this skill spot-checks against. - `skills/flow-linear-scaffold/SKILL.md` --- sibling sub-skill that creates net-new FDA milestones; runs after this skill in retrofit mode. - `skills/flow-preflight/SKILL.md` --- preceding sub-skill; preamble's `MODE=retrofit` gates this skill's invocation. - `docs/design-rationale/fda-plugin-interview.md` Q59 --- deprecate-legacy scope widening + user-invocable lift. - `commands/deprecate-legacy.md` --- Phase 5 orchestrator; second consumer of this skill's mapping cascade.