jocyscom/focuslogger/solution-patterns

Solution Patterns (Code ↔ UI ↔ Test path governance)

Core idea: The code folder is the single source of truth. UI routes and test paths are derivable from code paths via stack-specific rules. Once the mapping is explicit and machine-readable, "where does X live?" stops being a guess.

1. Why this skill exists

The `qa-tester` skill already proved the value of a deterministic Code → Test mirror (§5.2 of qa-tester): you compute the test path from the product path with a pure string transform, and "locate or create the test for file X" becomes a one-shot answer instead of a semantic search.

This skill generalises that idea along two axes:

1. The folder/code spine — every artifact (page, controller, model, test, CSS, migration, sqlproj item) sits somewhere in the solution's folder tree. The folder path is the artifact's primary key; nothing else needs to be invented.
2. Typed correspondences between artifacts — given one artifact, deterministic rules derive the others that correspond to it: its test, its URL route, its breadcrumb, its sidebar position, its REST endpoint, its companion file (e.g. .cshtml ↔ .cshtml.cs), its SQL table.

A single page like Pages/Agents/Jobs/Index.cshtml projects into all four navigation forms — URL route /Agents/Jobs, breadcrumb Home > Agents > Jobs, sidebar position under "Agents", and (if exposed) REST endpoint GET /api/agents/{id}/jobs — from the same spine coordinate. The skill stores one nav column per artifact and derives breadcrumb and sidebar as projections; it does not duplicate them.

When the spine and the correspondence rules are machine-readable, the AI can:

• Predict every related path before a file is read ("add a Dashboard page" → code path, route, breadcrumb, sidebar parent, test path, AutomationId — all known in advance).
• Generate complete navigation views (route table, breadcrumb map, sidebar tree) from code alone.
• Flag artifacts that disagree with the project's declared convention.
• Nudge a messy project toward consistency incrementally, instead of a single risky rewrite.

Correspondence types and ownership — this skill owns only the path-derivable ones:

1.5. The chain — folder spine on top, typed correspondences below

The clearest way to see how the layers fit is as a tree where the folder spine sits on top as SSOT, code projects branch off it, files live in the projects, and typed edges connect files to their corresponding artifacts in other branches.

{Solution}/                                ← FOLDER SPINE (top SSOT — every artifact lives here)
│
├── {Project}/                             ← code project (csproj) — primary code branch
│   ├── {Sub}/{Name}.cs                    ← code file (page model, controller, view-model, …)
│   │   ├─ companion ──────────────────→   {Sub}/{Name}.{paired-ext}            (e.g. .cshtml ↔ .cshtml.cs, .xaml ↔ .xaml.cs)
│   │   ├─ path-mirror ────────────────→   ../{Project}.Tests/{Sub}/{Name}Tests.cs
│   │   ├─ folder→route ───────────────→   /{Sub}/{Name}                        (URL — for Role=page)
│   │   │     ├─ projection ──────────→    Home > {Sub} > {Name}                (breadcrumb, derived)
│   │   │     └─ projection ──────────→    sidebar position under "{Sub}"       (derived)
│   │   └─ convention ─────────────────→   {Name}Service, I{Name}Repository     (review-only — owned by developer.instructions.md)
│   ├── Api/{Endpoints}.cs                 ← REST endpoints
│   │   └─ folder→endpoint ────────────→   {VERB} /api/{path}                   (REST URL — for Role=endpoint)
│   ├── Models/{Name}.cs                   ← model class
│   │   └─ name-mapping ───────────────→   dbo.{Name}                           (SQL table — direction declared in .instructions.md)
│   └── wwwroot/css/{stylesheet}.css       ← style file
│         ←── reference ────────────────   markup `class="..."` references      (owned by layout-guidelines.instructions.md)
│
├── {Project}.Tests/                       ← test project (mirrors {Project}/ structurally — qa-tester §5.2)
│   └── {Sub}/{Name}Tests.cs               ←── path-mirror of {Project}/{Sub}/{Name}.cs
│                                              (linked by qa-tester `@under-test` header)
│
└── {DataProject}/                         ← SQL Data project — canonical iff `.instructions.md` declares it so
    └── dbo/Tables/{Name}.sql
          ──── {Generator}.ps1 ────────→   generates {Project}/Models/{Name}.cs (mirrored, not hand-edited)

Reading the diagram:

• Vertical edges (`├── └──`) are containment — the folder hierarchy. This is the only universal SSOT.
• Horizontal arrows (`──→`) are typed correspondences — each one is one of the six types in §1's table. Some are path-derivable (in the CSV); others are reference-based or convention-only (owned elsewhere).
• Direction matters for name-mapping. SQL ↔ Model is bidirectional in shape but unidirectional in authority — the per-project .instructions.md declares which side is canonical (in this repo: SQL is canonical, models are generated by Generate-Models.ps1).
• Breadcrumb and sidebar are projections, not separate nodes. They derive from the URL tree once every page row's route + title is known. The CSV stores the route; pattern_map.py emits the breadcrumb map and sidebar tree as a sidecar view (§4.1).
• Tests are first-class. The path-mirror edge from every code file to its test file is the qa-tester §5.2 rule, reused verbatim by this skill — the join column in the CSV is ExpectedTestPath.
• The expectation invariant (§2 #2) is the payoff. A reader looking at any node should be able to imagine — without searching — the corresponding nodes in every other branch: sidebar entry → code path → URL → breadcrumb → test path → SQL table → model file. When the diagram fits the codebase, navigation becomes a free reference index. When a node breaks the pattern, every future read pays a search tax. Off-convention placement is a defect (off-convention in §5), not a design choice; declared overrides in .instructions.md are the only legitimate exceptions.

2. First principles

Each rule has a Why so you can judge edge cases instead of pattern-matching on the rule.

1. The folder/code spine is the universal SSOT for path-based correspondences. UI routes, breadcrumbs, sidebar positions, REST endpoints, test paths, and companion files are all derived from code paths. Why: folders are what the filesystem, git, and the IDE navigate by — deriving the other artifacts means they're always in sync with reality, not a stale hand-maintained list. This is the default direction for derivation when nothing yet exists; during refactors, principle #2 applies.

1. Bidirectional simplification (two-way street). When two components in the chain share a structural relationship — code ↔ folder, folder ↔ route, route ↔ REST endpoint, route ↔ breadcrumb ↔ sidebar, code ↔ test (mirror), code ↔ companion, model ↔ SQL table, descriptor catalog ↔ generated form — always consider adjusting either side to simplify the other. The right fix is whichever change makes the joint system smaller and more consistent: sometimes rename a controller to match a clean route, sometimes rename the route to match a clean controller; sometimes move a file to match its sidebar position, sometimes restructure the sidebar to match the file. Do not treat one side as immutable. Why: principle #1 sets the default derivation direction when nothing yet exists. During refactors, both sides are existing artifacts; treating either as sacred forces ugly names on the other for no engineering benefit. The rule keeps the joint system the focus, not the individual side. How to apply: propose the rename that produces (a) the smaller diff, (b) the cleaner naming, and (c) the fewer downstream renames. Exceptions: extremely rare when all components live in one solution. Hard exceptions — a wire format other systems already consume, a schema with external readers, a public API contract you don't own — must be named explicitly in .instructions.md before any workaround is added. Reference-based pairs (markup ↔ CSS) follow the same principle but are owned by `layout-guidelines.instructions.md`; convention-only pairs ({Name} ↔ {Name}Service ↔ I{Name}Repository) follow it under developer.instructions.md.

1. The expectation invariant: any one layer must let a reader imagine the others — divergence is a defect. Looking at a sidebar entry like {Sub} > {Name} should let any developer or AI predict, without searching: the code path ({Project}/{Sub}/{Name}.{ext}), the URL (/{Sub}/{Name}), the breadcrumb (Home > {Sub} > {Name}), the test path ({Project}.Tests/{Sub}/{Name}Tests.cs), and — when an SSOT direction is declared — the SQL table (dbo.{Name} or similar) and the model file. The reverse must also hold: opening any code file should let a reader predict its sidebar entry, URL, breadcrumb, REST equivalent, and test path. Why: mirrored layers turn navigation into a free reference index — every "where is X?" question becomes a string transform instead of a grep. The moment any layer stops mirroring, every future read of the codebase pays a search tax that compounds with every new file. How to apply: before placing a new file, mentally derive the sidebar entry, URL, and test path it implies; if any of those would surprise a careful reader, fix the placement, not the entry — and use principle #2 to decide which side moves. Exceptions: genuinely rare — must be declared in .instructions.md with an explicit "why" (compliance constraint, third-party contract, externally-frozen schema, historical migration). An undeclared deviation is always a defect — its strongest signal is the off-convention code in §5; a declared deviation is a recorded override.