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.

2. 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.

3. 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.

4. Name-mapping correspondences have a per-project canonical direction. SQL table ↔ model class can have either side as SSOT — Code-First (model canonical, SQL generated by EF migrations) or Database-First (SQL canonical, models generated by a script). Why: the choice depends on who owns the schema and who consumes it. The per-project .instructions.md declares the direction (see §4); the deviation report respects it — drift means the generated side is stale, never the canonical side.

5. Opinionated defaults per stack, explicit overrides per project. The skill ships default patterns in references/. A repo records its actual patterns in .ai/solution-patterns.instructions.md — that file overrides the defaults. Why: one-size-fits-all fights Angular's deliberate divergence from route=folder mirroring; no-defaults-at-all fails green-field projects that have nothing declared yet.

6. Record deviations, don't silently enforce. When a file deviates from both the project's declared pattern AND the stack default, flag it with a deviation code. Recommend moving only when the deviation is arbitrary ("the developer had no information on expected patterns when they created it") — not when the .instructions.md documents an intentional choice. Why: a flagged mismatch is a conversation, not a build failure. Projects evolve faster than rewrites.

7. The CSV is generated; the .instructions.md is written by humans. scripts/pattern_map.py regenerates .ai/solution-patterns.csv on demand. Never hand-edit the CSV — it gets overwritten. Never auto-generate the .instructions.md (except as a first draft during onboarding) — its value is the human reasoning behind each override. Why: mixing generated and hand-written data in one file guarantees losing one or the other.

8. Every rule in the skill has a Why. If you can't explain the motivation for a pattern, it's dogma the next AI will misapply. Why: (the rule itself is the demonstration.)

9. Prefer subtraction. Remove any stack rule, default, or deviation code that earns its keep fewer than 1 call in 20. Why: this file must stay under ~400 lines or it stops being loaded as reference and starts being skipped as noise.

3. Decision matrix — pick the stack reference file

Once scripts/detect_stack.py has identified the stack(s) in the repo, load only the reference file(s) you actually need:

Repos with multiple stacks (e.g. ASP.NET Core + WPF in the same solution) load all matching reference files. Each stack owns its rows in the CSV independently.

4. The per-project contract

Two files, both at .ai/ inside the target repo — never inside the skill itself:

.ai/solution-patterns.instructions.md (human-written, overrides defaults)

Minimal shape — the AI drafts this during onboarding; the human confirms and edits:

# Solution Patterns — declared for this repo

## Detected stacks
- aspnet-core (from `{WebProject}/{WebProject}.csproj` — `Microsoft.NET.Sdk.Web`)
- sql-data (from `{DataProject}/{DataProject}.sqlproj`)

## SSOT directions

For correspondences where either side could in principle be canonical, declare which is.

### sql-model
- **Canonical side:** SQL Data project (`{DataProject}/{DataProject}.sqlproj`).
- **Generated side:** model classes under `{WebProject}/Data/`.
- **Generator:** `{WebProject}/Data/Generate-Models.ps1`.
- **Why:** schema is shared with other systems and DBA-owned; models are a consumer view.
- **Implication for the deviation report:** if a model drifts from its table, the *model* is stale — regenerate. Hand-edits to generated model files are flagged as `manual-edit-of-generated`.

## Overrides

### aspnet-core
- `http_api = <flat>` — minimal-hosting endpoints registered in `{WebProject}/Api/ApiEndpoints.cs`; no `Controllers/` or per-resource files.
  - **Why:** the API is a small façade; full MVC controllers would add ceremony for no benefit.
  - **Recommended future direction:** if endpoints grow past ~15, split into `{WebProject}/Api/{Area}Endpoints.cs`.

.ai/solution-patterns.csv (generated, one row per artifact)

One row per code file. Columns — names are the contract, don't rename them. Path-derivable correspondences get a column; reference-based and convention-only ones don't (they're owned by layout-guidelines.instructions.md and developer.instructions.md respectively).

Why a CSV, not JSON/YAML: Excel-native, diffable in PR review, trivially grep-able, and the column contract forces a flat shape. Power Query can refresh an Excel view straight from the file — see assets/ for an optional template (deferred for v1).

.ai/solution-patterns.nav.json (derived sidecar — DO NOT hand-edit)

Generated from the CSV by pattern_map.py. Three projections of the URL tree, computed from Role=page rows + their ExpectedNavPath + page titles:

• Route table: { "/Agents/Jobs": { codePath: "...", title: "Jobs" }, ... } — every page keyed by route.
• Breadcrumb map: { "/Agents/Jobs": ["Home", "Agents", "Jobs"], ... } — each route's parent walk joined into a breadcrumb.
• Sidebar tree: nested { name, route, children: [...] } — pages grouped by URL parent into a navigable tree.

These are pure projections — never hand-edit; regenerate. They give the AI human-readable navigation without bloating CSV columns. Compare this sidecar against the project's actual sidebar source (e.g. a NavTree.cs, sidebar XAML, or _Layout.cshtml partial — exact location lives in the per-project .instructions.md) to catch nav-tree drift from the route truth.