DC-172/DC-228: Documentation, ADRs, skills, and repo cleanup (1/4)

.claude/skills/figma-verify/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: figma-verify
+description: Compare running app screens against Figma designs — captures screenshots from both sources and produces a structured gap report
+allowed-tools: mcp__plugin_figma_figma__get_screenshot, mcp__plugin_figma_figma__get_design_context, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_close, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_wait_for, Read, Bash(mkdir:*), Bash(ls:*), Bash(rm:*)
+argument-hint: <figma-file-key> <app-base-url> <screen-mappings...>
+---
+
+# Figma Design Verification
+
+Compare a running application against Figma designs and produce a structured gap report.
+
+## Overview
+
+This skill captures screenshots of both the Figma designs and the live app, then performs a visual comparison to identify layout, content, styling, and asset gaps. The output is a markdown report with actionable items.
+
+All screenshots are saved to `.claude-figma-verify/` (gitignored) so the user can review them side-by-side after the report.
+
+## Arguments
+
+Parse `$ARGUMENTS` as positional values:
+
+| Position | Name | Example | Required |
+|----------|------|---------|----------|
+| 1 | Figma file key | `32kDQ73MSbUNdAsVi8fQzF` | Yes |
+| 2 | App base URL | `http://localhost:3099` | Yes |
+| 3+ | Screen mappings | `landing=6034:16454=/` | Yes (at least one) |
+
+**Screen mapping format:** `<name>=<figma-node-id>=<app-route>`
+
+Example invocation:
+```
+/figma-verify 32kDQ73MSbUNdAsVi8fQzF http://localhost:3099 landing=6034:16454=/ disclaimer=6736:19904=/disclaimer personalInfo=6034:16775=/check review=8028:29275=/review
+```
+
+If arguments are missing or malformed, ask the user to provide them.
+
+## Execution Steps
+
+### 1. Parse and Validate
+
+Extract the file key, base URL, and screen mappings from `$ARGUMENTS`. For each mapping, parse into:
+- `name` — human-readable screen name
+- `nodeId` — Figma node ID (colon-separated, e.g. `6034:16454`)
+- `route` — app route path (e.g. `/disclaimer`)
+
+Validate that at least one screen mapping is provided.
+
+### 2. Set Up Screenshot Directory
+
+```bash
+mkdir -p .claude-figma-verify/figma .claude-figma-verify/app
+```
+
+This directory is gitignored. Clean up any previous run's files:
+```bash
+rm -f .claude-figma-verify/figma/*.png .claude-figma-verify/app/*.png
+```
+
+### 3. Set Browser Viewport
+
+Resize the Playwright browser to mobile width to match the Figma mobile designs:
+
+- **Width:** 375
+- **Height:** 812
+
+### 4. Capture Figma Screenshots (Prototype URL Pass)
+
+Save Figma design screenshots to disk using Figma's prototype presentation view in Playwright. This renders the design frame cleanly with minimal UI chrome.
+
+**For each screen mapping:**
+
+1. Navigate Playwright to the prototype URL:
+   ```
+   https://www.figma.com/proto/{fileKey}/?node-id={nodeId}&scaling=min-zoom
+   ```
+   Replace `:` with `-` in the node ID for the URL (e.g., `6034:16454` → `6034-16454`).
+
+2. Wait 5 seconds for the canvas to render (Figma uses WebGL):
+   ```
+   browser_wait_for(time: 5)
+   ```
+
+3. Take a viewport screenshot (NOT full-page — the prototype view fits the frame to the viewport):
+   ```
+   browser_take_screenshot(filename: ".claude-figma-verify/figma/<name>.png")
+   ```
+
+4. After saving to disk, also call `mcp__plugin_figma_figma__get_screenshot` with the file key and node ID. This gives you a higher-fidelity inline image for the visual comparison analysis — the MCP renders at native Figma resolution without browser chrome. Use this inline image as the primary source for your gap analysis.
+
+**IMPORTANT:** The Figma MCP is READ-ONLY. Never use write/modify tools.
+
+**Note:** The prototype URL requires the Figma file to have link sharing enabled. If the page fails to load or shows a login wall, note it in the report and fall back to MCP-only screenshots (inline comparison without disk files).
+
+### 5. Navigate the Full Flow and Capture App Screenshots
+
+**Do NOT navigate directly to each route.** Many screens depend on application state (e.g., the review page needs children in context). Instead, navigate the app as a user would, following the screen mappings in order:
+
+1. Start at the first screen's route (typically `/`)
+2. Capture the screenshot for that screen
+3. Interact with the app to advance to the next screen (click buttons, fill forms as needed)
+4. Capture each subsequent screen after reaching it through the flow
+
+**Form filling strategy:**
+- Use realistic but fake data (e.g., "Jane", "M", "Doe", birthdate January 15 2015)
+- Fill all required fields before advancing
+- If multiple children are needed (e.g., review page shows 3 cards), add multiple children through the form flow before capturing the review screen
+
+**Capturing screenshots:**
+Use `mcp__plugin_playwright_playwright__browser_take_screenshot` with:
+- `fullPage: true`
+- `filename: .claude-figma-verify/app/<name>.png`
+
+**If a screen cannot be reached through the flow** (e.g., a closed/error state), note it in the report as "requires manual setup" and capture what's available.
+
+### 6. Visual Comparison
+
+For each screen, compare the Figma screenshot (inline MCP image) against the app screenshot. Evaluate these dimensions:
+
+| Dimension | What to Check |
+|-----------|--------------|
+| **Layout** | Element order, spacing, alignment, grid structure |
+| **Typography** | Headings, body text size/weight, hierarchy |
+| **Colors** | Background, text, button, accent colors |
+| **Components** | Buttons, inputs, accordions, cards — do they match USWDS patterns shown in Figma? |
+| **Assets** | Logos, icons, illustrations — present and correctly sized? |
+| **Content** | Text content matches (accounting for i18n placeholder text in app) |
+| **Responsive** | Does the mobile layout match the Figma mobile frame? |
+
+### 7. Generate Report
+
+Produce a structured markdown report. Format:
+
+```markdown
+## Figma Verification Report
+
+**Figma file:** `<file-key>`
+**App URL:** `<base-url>`
+**Viewport:** 375 × 812
+**Date:** YYYY-MM-DD
+**Screenshots:** `.claude-figma-verify/` (figma/ and app/ subdirectories)
+
+---
+
+### Summary
+
+| Screen | Status | Gaps |
+|--------|--------|------|
+| Landing | ✅ Match | 0 |
+| Disclaimer | ⚠️ Minor gaps | 2 |
+| Personal Info | ❌ Major gaps | 4 |
+
+---
+
+### Screen: <Name>
+
+**Figma:** `.claude-figma-verify/figma/<name>.png`
+**App:** `.claude-figma-verify/app/<name>.png`
+
+**Status:** ✅ Match | ⚠️ Minor gaps | ❌ Major gaps
+
+**Matches:**
+- [list what matches well]
+
+**Gaps:**
+
+| # | Dimension | Severity | Description | Suggestion |
+|---|-----------|----------|-------------|------------|
+| 1 | Assets | 🔴 Major | Missing logo above heading | Add `<Image>` with logo from Figma |
+| 2 | Spacing | 🟡 Minor | Extra margin below button | Adjust `margin-bottom` class |
+
+---
+```
+
+#### Severity Levels
+- 🔴 **Major** — Missing elements, wrong layout structure, broken functionality
+- 🟡 **Minor** — Spacing differences, slight color mismatches, font weight variations
+- 🟢 **Trivial** — Sub-pixel differences, animation timing, hover states
+
+### 8. Cleanup
+
+Close the Playwright browser when done.
+
+## Rules
+
+- **READ-ONLY Figma:** Never use Figma write/modify MCP tools. Only `get_screenshot` and `get_design_context`.
+- **No automatic fixes:** This skill only reports gaps. Do not modify application code. If the user wants fixes, they will ask separately.
+- **i18n tolerance:** The app may show placeholder text or translation keys. Note these as content gaps only if the Figma design shows specific text that doesn't appear at all.
+- **USWDS tolerance:** Minor rendering differences between USWDS components and Figma mockups are expected. Only flag structural differences (wrong component type, missing component).
+- **Always show both screenshots:** The report should reference both the Figma and app screenshots so the user can visually confirm findings.
+- **Full-page screenshots:** Always use `fullPage: true` for app screenshots to capture below-the-fold content.
+- **Save all screenshots to disk:** Both Figma and app screenshots must be saved to `.claude-figma-verify/` so the user can review them after the session.
+- **Navigate the flow, don't jump:** Always reach screens through the normal app flow to ensure correct application state. Only use direct navigation for the starting screen.
+
+## Edge Cases
+
+- **App not running:** If navigation fails, report the error and skip that screen. Continue with remaining screens.
+- **Figma node not found:** If the Figma screenshot fails, report it and skip that screen.
+- **Figma login wall:** If the prototype URL redirects to a login page instead of rendering the design, fall back to MCP-only inline screenshots. Note in the report that Figma screenshots could not be saved to disk because the file requires authentication. The user may need to enable link sharing on the Figma file.
+- **Interactive states:** If a screen requires interaction beyond simple form filling (e.g., API responses, error states), note it as "requires manual setup" and describe what state is needed.
+- **No arguments provided:** Show the usage format and example invocation, then ask the user to provide arguments.

.claude/skills/multi-repo-git/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: multi-repo-git
+description: Use when performing git operations (sync, branch, status) across the SEBT multi-repo project — switching branches, pulling latest, creating feature branches, or checking repo state
+allowed-tools: Bash(git -C:*)
+---
+
+# Multi-Repo Git Operations
+
+Manage git operations across the SEBT portal's four repositories in parallel.
+
+## Repositories
+
+```
+# Assumes all four SEBT repos are sibling directories under a common parent
+SEBT_BASE="$(dirname "$(git rev-parse --show-toplevel)")"
+
+portal="$SEBT_BASE/sebt-self-service-portal"
+state_connector="$SEBT_BASE/sebt-self-service-portal-state-connector"
+dc_connector="$SEBT_BASE/sebt-self-service-portal-dc-connector"
+co_connector="$SEBT_BASE/sebt-self-service-portal-co-connector"
+```
+
+All git commands MUST use `git -C <repo-path>` to be explicit about the target directory.
+
+## Operations
+
+### sync — Checkout main and pull latest
+
+Default: all four repos. User may specify a subset.
+
+1. Run `git -C <path> checkout main` on each repo (parallel)
+2. Run `git -C <path> pull` on each repo (parallel)
+3. Report results in a summary table
+
+### branch — Create or checkout a feature branch
+
+Requires: branch name from user, and which repos to target (ask if not specified).
+
+- To create: `git -C <path> checkout -b <branch>`
+- To checkout existing: `git -C <path> checkout <branch>`
+
+Run in parallel across targeted repos. Report results.
+
+### status — Show state of all repos
+
+Run `git -C <path> status --short --branch` on all four repos in parallel.
+
+Present as a summary table:
+
+| Repo | Branch | Clean? | Tracking |
+|------|--------|--------|----------|
+
+## Rules
+
+- **Parallel execution:** Always run independent git commands across repos in parallel (multiple Bash tool calls in one message).
+- **Atomic commands:** Each `git -C` call is a separate Bash invocation. Never chain with `&&` or `;`.
+- **Read-only by default:** Only `sync` and `status` run without confirmation. For `branch`, confirm the branch name and target repos before executing.
+- **Always summarize:** End every operation with a concise table showing results per repo.

.claude/skills/review-prep/SKILL.md

@@ -0,0 +1,134 @@
+---
+allowed-tools: Bash(git:*), Bash(wc:*), Bash(grep:*), Bash(find:*), Bash(head:*), Bash(tail:*), Bash(printf:*), Bash(shasum:*), Read
+argument-hint: [repository](default: sebt-self-service-portal) [base-branch|commit-ref] (default: main)
+description: Analyze code changes and generate a summary and prioritized human review guide. Use for larger PRs or preparing code for review.
+---
+
+# PR Review Priority Analysis
+
+Generate a prioritized review guide for human reviewers. Our analysis will identify which code changes warrant the most human attention.
+
+## Execution Steps
+
+### 1. Determine Diff Source
+
+Parse `$ARGUMENTS` to determine comparison target:
+- Empty or "main" → `git diff main...HEAD`
+- Branch name → `git diff <branch>...HEAD`  
+- Commit ref (SHA, HEAD~N) → `git diff <ref>`
+- "staged" → `git diff --cached`
+- "unstaged" → `git diff`
+
+Verify the ref exists before proceeding. If invalid, report available branches.
+
+### 2. Gather Change Metrics
+
+```bash
+# Get list of changed files with stats
+git diff <ref> --stat
+
+# Get detailed diff for analysis
+git diff <ref> --unified=3
+```
+
+Extract:
+- Files added, modified, deleted
+- Lines added/removed per file
+- Total change volume
+
+### 3. Identify Review Units
+
+For each changed file, identify discrete units requiring review:
+- **New functions/methods**: Extract function name and line range
+- **Modified functions**: Note what changed
+- **Configuration changes**: Flag separately
+- **Documentation changes**: identify semantically distinct chunks of docs
+- **New files**: Entire file is one unit 
+
+
+Use language-appropriate patterns:
+- Python: `def `, `class `, `async def `
+- Ruby: `def`, `class`, `module`
+- JavaScript/TypeScript: `function `, `const.*=.*=>`, `class `, `export `
+- Go: `func `
+- Java or C#: Method signatures, class declarations
+
+### 4. Score Each Unit
+
+Evaluate each review unit against three criteria:
+
+#### Security Risk (Weight: Highest)
+🔴 **High**: Authentication, authorization, secrets/credentials, storing personal information, file system access, network requests, and so on
+🟡 **Medium**: Configuration, permissions, logging (if potential for PII leaks), session handling, rate limiting
+🟢 **Low**: Pure computation, display logic, tests, documentation, styling
+
+#### Complexity (Weight: Medium)
+🔴 **High**: Deep cyclomatic complexity, multiple code paths, recursive logic, complex conditionals, concurrent/async patterns, 
+🟡 **Medium**: Moderate branching, callbacks, error handling paths
+🟢 **Low**: Linear flow or simple conditionals, simple CRUD, straightforward transformations
+
+#### Novelty (Weight: Medium)
+🔴 **High**: New libraries, significant departures from existing code
+🟡 **Medium**: first-of-kind in codebase or moderate variations on existing patterns
+🟢 **Low**: Boilerplate, repeated patterns; stuff that clearly builds on well-known patterns or code that already exists in code base
+
+Also generate an aggregate rating and, for medium or high risk, concisely explain (2-6 words) the reason for attention
+
+### 5. Generate Output
+
+#### Format: Markdown Report
+
+```markdown
+## PR Review Priority Guide
+
+**Risk Level**: [🔴 High | 🟡 Medium | 🟢 Low] | **Files**: N | **Lines**: +X / -Y
+
+[1-2 sentence summary: what this PR does and where reviewer attention is needed]
+
+---
+
+### Priority Review Table
+
+| Priority | File | Function/Change | Lines | Sec | Cpx | Nov | Notes |
+|:--------:|------|-----------------|:-----:|:---:|:---:|:---:|-------|
+| 🔴 | `path/to/file.py` | `authenticate_user()` | 45-89 | 🔴 | 🟡 | 🔴 | New auth flow, handles tokens |
+| 🔴 | `api/medicaid.py` | `process_household()` | 112-156 | 🔴 | 🟢 | 🟡 | New data model with sensitive PII |
+| 🟡 | `utils/cache.py` | `invalidate_all()` | 23-45 | 🟢 | 🟡 | 🟡 | New cache pattern |
+| 🟢 | `models/user.py` | `UserProfile` class | 1-34 | 🟢 | 🟢 | 🟢 | Standard model |
+
+---
+
+### Summary by Priority
+
+**🔴 Critical Review (N items)**
+- List critical items with brief rationale
+
+**🟡 Recommended Review (N items)**  
+- List medium-priority items
+
+**🟢 Low Priority (N items)**
+- Boilerplate, tests, config (can be skimmed)
+
+---
+
+### Review Recommendation
+
+[Actionable guidance: "Start with auth/oauth.py lines 45-89, then review payment logic. Test files can be skimmed for coverage gaps."]
+```
+
+## Output Guidelines
+
+- Sort table by priority (🔴 → 🟡 → 🟢), then by file path
+- Files should be links, where the link text is a path from the repo root, and the URL will jump directly to the first line of the range in the PR changeset. Use shasum if needed to generate the links.
+- Line numbers should be clickable-friendly (exact ranges). 
+- Keep notes column concise (under 40 chars)
+- For very large PRs (50+ review units), group by directory and show top 20 critical items with a note about remaining
+- If no 🔴 items exist, explicitly state "No critical security concerns identified"
+- Always include the aggregate risk assessment
+
+## Edge Cases
+
+- **No changes found**: Report "No changes detected against <ref>"
+- **Binary files**: Note as "binary file changed" with 🟡 priority
+- **Renamed files**: Track as low priority unless content also changed
+- **Deleted files**: List separately; generally low priority unless removing security controls