@codyswann/lisa 2.119.1 → 2.121.1

package/plugins/lisa-copilot/rules/eager/usage-accounting.md

@@ -0,0 +1,28 @@
+# Usage Accounting (load-bearing)
+
+Lisa attaches AI usage and cost telemetry to every artifact it creates/updates. The format is a single canonical managed section.
+
+## Managed section
+
+Every artifact with inline body content gets exactly one section:
+
+```markdown
+## Lisa Usage
+```
+
+**Canonical. Rewrite in place; never append a second usage section.** If the host can't safely edit body, write the same section in a comment and treat that comment as the managed artifact for future rewrites.
+
+## Required field semantics
+
+Each direct entry records ONE logical Lisa run on ONE artifact. `entry_id` is the stable dedupe key — rewriting the same logical run with the same `entry_id` updates in place; a different run gets a different `entry_id`.
+
+- **`source`**: `observed` (runtime supplied) / `estimated` (derived from trustworthy metadata + pricing contract) / `unavailable`.
+- **`pricing_status`**: same trinary plus `missing` (cost not known but should be).
+- **Absence ≠ zero.** `null` means unknown; `0` means explicitly zero. Always write the entry — never silently omit.
+- Do NOT replace observed counts with estimates.
+
+## Rollup
+
+Container artifacts (Epic, PRD, etc.) roll up usage from their direct children. Roll-up is recursive — a parent's `## Lisa Usage` aggregates its descendants' direct entries. Re-writes are idempotent: re-running an intake or lifecycle skill must not duplicate entries.
+
+Full schema (all 17 fields, pricing semantics, rollup math, idempotent-rewrite rules): [reference/usage-accounting.md](../reference/usage-accounting.md).

package/plugins/lisa-copilot/rules/eager/verification.md

@@ -0,0 +1,21 @@
+# Empirical Verification (load-bearing)
+
+**Verification is not linting, typechecking, or testing.** Those are *quality checks* — necessary prerequisites, but NOT verification.
+
+**Verification is using the resulting software the way a user would** — interacting with the UI, calling the API, running the CLI, observing behavior. Tests pass in isolation; verification proves the system works as a whole.
+
+## Mandatory
+
+- **Never claim success without runtime evidence.** "The code looks correct" is not evidence.
+- **If all you did was run tests, typecheck, and lint — you have NOT verified.**
+- **Before starting implementation, state your verification plan** — how you will USE the resulting software to prove it works. A plan that only lists `test`/`typecheck`/`lint` commands is not a plan. Do not begin until confirmed.
+- **After verifying empirically, codify it as a regression test** via the `codify-verification` skill — Playwright for UI, integration test for API/DB/auth, benchmark for performance. Codification is mandatory for every verification type except PR/Documentation/Deploy and Investigate-Only spikes.
+- **Every PR must include reviewer replay steps** — the exact human steps to use the software and confirm the change works. Not test commands. If a reviewer can't reproduce from the PR description alone, the PR is incomplete.
+
+## Roles
+
+- **Builder agent** — implements the change.
+- **Verifier agent** — acts as the end user / API client / operator. Independent from Builder when possible.
+- **Human overseer** — approves risky operations and anything agents cannot fully verify.
+
+Full operational contract (verification types, evidence formats, escalation protocol): [reference/verification.md](../reference/verification.md).

package/plugins/lisa-copilot/rules/eager/wiki-knowledge-source.md

@@ -0,0 +1,16 @@
+# Wiki as Knowledge Source (load-bearing)
+
+If the project has an LLM Wiki (a `wiki/` directory with `index.md`), treat it as the canonical source of durable project knowledge.
+
+Before researching background, conventions, ownership, architecture, glossary, or "how/why does X work here":
+
+1. **Consult the wiki first.** Start from `wiki/index.md` or use the wiki query skill (`/lisa-wiki-query`).
+2. **Use what the wiki says** as the authoritative answer when it covers the question — do not re-derive it from raw sources.
+3. **Fall back to primary sources** (code, tickets, commit history, external docs) only when the wiki is silent, ambiguous, or contradicted by what you observe.
+4. **Surface gaps.** If the wiki is wrong, stale, or missing knowledge that belongs there, flag it — and where the workflow supports it, capture the correction via `/lisa-wiki-ingest`.
+
+The wiki documents knowledge; it does NOT override executable behavior. When wiki and running code disagree about what the system does, trust the code and treat the wiki as out of date.
+
+If the project has no `wiki/`, this rule does not apply.
+
+Full prose: [reference/wiki-knowledge-source.md](../reference/wiki-knowledge-source.md).

package/plugins/lisa-copilot/rules/reference/base-rules.md

@@ -0,0 +1,133 @@
+Intent Routing (FIRST — before anything else):
+
+Before starting any work in a session, classify the user's initial request using the Intent Routing rule. Determine which flow applies (Research, Plan, Implement, Verify, or None) and check its readiness gate. Once a flow is established, all subsequent messages operate within it. Do not skip this step — even if the request seems simple. See the `intent-routing` rule for the full protocol.
+
+Orchestration Selection (SECOND — immediately after classifying the flow):
+
+After echoing the chosen flow and BEFORE doing any work, state the orchestration mode explicitly — either `Orchestration: agent team` or `Orchestration: single agent` — with a one-sentence justification. This echo is mandatory and must appear in the same message as the flow classification.
+
+Default to an agent team for Research, Plan, Implement (Build/Fix/Improve/Investigate-Only), and any flow that invokes the Review sub-flow. Use a single agent only for Verify (standalone) and Monitor (standalone). See the `intent-routing` rule's Orchestration section for the full decision matrix.
+
+When the mode is `agent team` **and you are not already operating inside an agent team**, your FIRST tool calls after the classification echo MUST establish team orchestration before any content-gathering work. Use the team tool for the current runtime: Claude uses `TeamCreate` (first `ToolSearch` with `query: "select:TeamCreate"` if needed); Codex must not call `TeamCreate` because Codex does not expose that Claude tool. In Codex, use `tool_search` with a query like `multi-agent tools` to load `multi_agent_v1`, then use `multi_agent_v1.spawn_agent` for teammate delegation and treat the first successful `spawn_agent` call as establishing team orchestration. Other runtimes should use their current tool-discovery mechanism to discover and call the appropriate multi-agent/team tool. If no team creation or subagent delegation tool is available, explicitly state that team orchestration is unavailable in this runtime, continue as the lead agent, and preserve the workflow's review, verification, and task-tracking obligations locally. Do not reach for `TaskCreate`, `Agent`, `Skill`, MCP tools, `Read`, `Bash`, or any other content-gathering call before the team exists, the first Codex teammate has been spawned, or the no-team fallback has been declared — those are bypass paths that skip durable task state and parallel review. Reading the ticket, exploring the code, querying the API are all tasks for the team, not for the lead session before orchestration exists. If you ARE already operating inside an agent team, do NOT create a second team and do NOT collapse into inline single-agent work; instead request the existing team lead add the specialist agent(s) this flow needs to the current team — on Claude, teammates cannot add named teammates (teams are flat), so message the lead with the teammate(s), assignments, and completion criteria; on Codex, ask the addressable lead/root to `multi_agent_v1.spawn_agent` them, or if no lead handle exists spawn the bounded specialists yourself, `wait_agent`, and relay results upward — then coordinate through the shared task state.
+
+Requirement Verification:
+
+Never assume the person providing instructions has given you complete, correct, or technically precise requirements. Treat every request as potentially underspecified. Before starting any work:
+
+1. Identify any ambiguities in the request that would prevent you from completing the work. If any exist, stop and ask for clarification.
+2. Identify any open questions whose answers would change your approach. If any exist, stop and ask.
+3. Define how you will empirically verify the work is complete — not by running tests or linters, but by using the resulting software the way a user would. If you cannot define this, stop and ask for clarification.
+4. If a request contradicts existing code, architecture, or conventions, do not silently comply. Raise the contradiction and confirm intent before proceeding.
+
+DO NOT START WORK if any of the above are unclear. Asking a clarifying question is always cheaper than implementing the wrong thing.
+
+Do not begin a task if there are any blockers, ambiguities, access requirements, unanswered questions, or unknowns that would prevent you from completing it. Identify these before starting — not during implementation. If you cannot confirm that you have everything needed to finish the work end-to-end, stop and surface what is missing.
+
+Project Discovery:
+- Determine the project's package manager before installing or running anything.
+- Read the project manifest (e.g. package.json, pyproject.toml, Cargo.toml, go.mod) to understand available scripts and dependencies.
+- Before defining a verification approach, check the `scripts` section of the project manifest for existing commands to start servers, run tests, seed databases, etc. Use existing scripts rather than inventing ad-hoc commands.
+- Read the project's linting and formatting configuration to understand its standards.
+- Regenerate the lockfile after adding, removing, or updating dependencies.
+- Ignore build output directories (dist, build, out, target, etc.) unless specified otherwise.
+- Ignore configuration linter hints/warnings — only fix actual unused exports/dependencies reported as errors.
+
+Code Quality:
+- Make atomic commits with clear conventional commit messages.
+- Create clear documentation preambles for new code. Update preambles when modifying existing code.
+- Document the "why", not the "what". Code explains what it does; documentation explains why it exists.
+- Always add new imports and their first usage in the same edit. The lint-on-edit hook runs `eslint --fix` after every Edit, which auto-removes unused imports. If you add an import in one edit and plan to use it in a second edit, the hook will strip the import before the second edit runs.
+- Add language specifiers to fenced code blocks in Markdown.
+- Use project-relative paths rather than absolute paths in documentation and Markdown.
+- Delete old code completely when replacing it. No deprecation unless specifically requested.
+- Fix bugs and issues properly. Never cover them up or work around them.
+- When a tool or build step fails, never assume the failure is pre-existing and work around it. Investigate the root cause first — check git history, find when it broke and why — before deciding how to proceed.
+- Test empirically to confirm something worked. Never assume.
+- Never assume test expectations before verifying actual implementation behavior. Run tests to learn the behavior, then adjust expectations to match.
+- Always provide a solution. Never dismiss something as "not related to our changes" or "not relevant to this task".
+
+Git Discipline:
+- Prefix git push with `GIT_SSH_COMMAND="ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=5"`.
+- Never commit directly to an environment branch (dev, staging, main).
+- Never use --no-verify or attempt to bypass a git hook.
+- Never bypass branch protection. Never use `--admin`, `--force`, or any other flag to merge a PR that has failing CI checks. If CI fails, fix it. If you cannot fix it, escalate to the human. There are zero exceptions. "Green in CI" is the definition of done — not "green locally." A PR is not complete until CI passes on the actual PR branch.
+- Never stash changes you cannot commit. Either fix whatever is preventing the commit or fail out and let the human know why.
+- Never add "BREAKING CHANGE" to a commit message unless there is actually a breaking change.
+- When opening a PR, watch the PR. If any status checks fail, fix them. For all bot code reviews, if the feedback is valid, implement it and push the change to the PR. Then resolve the feedback. If the feedback is not valid, reply to the feedback explaining why it's not valid and then resolve the feedback. Do this in a loop until the PR is able to be merged and then merge it.
+- When merging a PR into an environment branch (dev, staging, main), watch the resultant deploy until it fully succeeds. If it fails for any reason, fix the failure and then open a new PR with the fix.
+- When referencing a PR in a response, always include the url
+- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use a regular merge commit (`gh pr merge --merge`) as well.
+
+Testing Discipline:
+- Never skip or disable any tests or quality checks.
+- Never add skip directives to a test unless explicitly asked to.
+- Never lower thresholds to pass a pre-push hook. Increase test coverage to make it pass.
+- Never duplicate test helper functions without appropriate lint suppression when duplication is intentional for test isolation.
+
+JIRA Discipline:
+- If working on a JIRA issue, make sure the branch you're working on references and is added to the JIRA issue.
+- If working on a JIRA issue, update the issue as you work through it. For example, if working on a Bug Triage, update the issue with your questions/feedback/suggestions.
+- When reading a JIRA issue, always read ALL comments on the ticket — not just the description. Comments contain critical context: stakeholder decisions, scope changes, blockers, triage findings from other repos, and implementation notes. Use the Atlassian MCP or `jira issue view <TICKET_ID> --comments 100` to fetch them.
+- When requesting clarification on a JIRA issue, post the question as a comment using ADF (Atlassian Document Format) and @mention the Reporter so they receive a notification.
+- When creating JIRA tickets, establish issue link relationships (e.g. "is blocked by", "blocks", "relates to", "is duplicated by") between tickets that have dependencies or logical connections. Do not leave related tickets unlinked. Relationship discovery is mandatory on every create and update — search BOTH the local git history (`git log --all --grep=<keyword>`, `git log -- <path>`) AND Jira (JQL by component, keyword, label, epic siblings) before declaring "no related work." Record the searches you ran and their outcomes in the description (or a comment) so a reviewer can see the search was real.
+- Ticket scope by type: Bug, Task, and Sub-task tickets MUST be single-repo (one work unit, one repo). Epic, Spike, and Story tickets MAY span multiple repos. If a Bug/Task/Sub-task crosses repos, split it per the `repo-scope-split` rule — at PRD-decomposition time via `task-decomposition` step 1.5 (parent Story + per-repo children); at work-time (an existing ticket an agent is about to implement) via the work-time split procedure (narrow the original to one repo, spin off a sibling per additional repo cloning its metadata, link the producer→consumer dependency, then proceed). A cross-repo work unit is a decomposition error the agent fixes by splitting, not a reason to bounce the ticket to the reporter.
+- Ticket descriptions MUST contain everything an implementer needs to start work without asking the reporter. In particular:
+  - **Target backend environment** (`dev` / `staging` / `prod`) when the ticket has runtime behavior. QA/product report against a deployed env; the implementer verifies locally first against that backend before CI/CD. Skip only for doc-only, config-only, type-only, or Epic tickets.
+  - **Sign-in account / credentials** when the work requires being signed in. Name the account (or the source — 1Password item, env var, seeded fixture) and the role. Omit entirely when sign-in is not required.
+  - **Gherkin acceptance criteria** (Given/When/Then) so the implementer can verify behavior without guessing.
+  - **Relationship discovery evidence** — either an issue link to a related ticket, or a documented search showing none was found (see Relationship Discovery in jira-verify).
+- Ticket metadata MUST include an **epic parent** for non-bug, non-epic tickets so every Story/Task/Sub-task is traceable to a strategic goal.
+- Pre-flight gate before starting work on any ticket: if the description is missing target backend environment (when applicable), sign-in credentials (when applicable), Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence, transition the ticket to Blocked, reassign to the **Reporter**, and post a comment listing exactly what is missing. Do not start work. This is the one place where auto-transitioning status is allowed.
+- When checking for associated pull requests on a JIRA issue, check the **Development panel** — not just comments or description text. The Development panel shows PRs, commits, branches, and builds linked via the GitHub-Jira integration. Query it via the dev-status API:
+  ```bash
+  ISSUE_ID=$(curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \
+    "${JIRA_SERVER}/rest/api/2/issue/${TICKET_ID}?fields=id" | jq -r '.id')
+  curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \
+    "${JIRA_SERVER}/rest/dev-status/1.0/issue/detail?issueId=${ISSUE_ID}&applicationType=GitHub&dataType=pullrequest" \
+    | jq '.detail[].pullRequests[] | {title, status, url, source: .source.branch}'
+  ```
+
+Agent Behavior:
+- Never handle tasks yourself when working in a team of agents. Always delegate to a specialized agent.
+
+Pace:
+- Never rush. There is no pressure to finish quickly. Speed is not a measure of quality, and a fast wrong answer is worse than a slow correct one.
+- Take the time to read the relevant code in full, verify assumptions empirically, ask clarifying questions when something is ambiguous, and check your work before declaring it done.
+- Do not skip steps to save time — quality gates, verification, reading existing code, asking the user — these exist because shortcuts cost more than they save.
+- If a task feels like it's taking "too long," that is almost always a sign that the task is harder than it first appeared, not a sign that you should cut corners. Surface the difficulty to the user instead of compressing the work.
+- Optimize for being correct, thorough, and reversible. Time spent doing the work right is never wasted; time spent recovering from a rushed answer often is.
+
+NEVER:
+- Modify this file directly. To add a memory or learning, use the project's rules file or create a skill.
+- Directly modify files inside dependency directories (e.g. node_modules, .venv, vendor, target).
+- Delete anything that is not tracked in git.
+- Delete anything outside of this project's directory.
+- Create placeholder implementations.
+- Create TODOs.
+- Create versioned copies of files or functions (e.g. V2, Optimized, processNew, handleOld).
+- Write migration code unless explicitly requested.
+- Write functions or methods unless they are needed.
+- Write unhelpful comments like "removed code" or "old implementation".
+- Update CHANGELOG.
+
+ASK FIRST:
+- Before adding a lint or formatter suppression comment (e.g. eslint-disable, biome-ignore, prettier-ignore, noqa, #[allow(...)], @SuppressWarnings). These should be a last resort.
+- Before adding a type-checking suppression comment (e.g. ts-ignore, ts-expect-error, ts-nocheck, type: ignore).
+- Lint suppression in test files is acceptable without asking only when comprehensive test coverage requires it (e.g. file length limits) or when intentional duplication improves test isolation. Include matching re-enable comments where applicable.
+
+Multi-Repository Awareness:
+
+When working in a microservices architecture, the code you need may span multiple repositories. Watch for these signals that you're missing context:
+
+1. Import paths or package references that don't resolve in the current repository
+2. API calls to internal services where you can't find the contract, schema, or handler
+3. Shared libraries, SDKs, or proto/OpenAPI definitions referenced but not present
+4. Environment variables or config referencing service names you don't have code for
+5. Error messages or stack traces pointing to code outside the current repo
+6. JIRA issues or documentation referencing components in other repositories
+
+When you detect any of the above:
+1. Do NOT guess or make assumptions about what the external code does
+2. Identify which repository contains the missing code
+3. Add that repository to your current session before proceeding
+4. If you cannot determine which repository contains the code, ask — do not proceed without it

package/plugins/lisa-copilot/rules/reference/coding-philosophy.md

@@ -0,0 +1,428 @@
+# Coding Philosophy
+
+This rule enforces the core coding philosophy: **immutability**, **predictable structure**, **functional transformations**, **test-driven development**, **clean deletion**, and **simplicity**.
+
+## Guiding Principles: YAGNI + SOLID + DRY + KISS
+
+Follow these software engineering principles, **deferring to Occam's Razor/KISS whenever principles conflict**:
+
+### KISS (Keep It Simple, Stupid) - The Tiebreaker
+
+When principles conflict, **always choose the simpler solution**.
+
+```typescript
+// KISS: Simple direct approach
+const isAdmin = user.role === "admin";
+
+// Over-engineered: Abstraction without value
+const isAdmin = RoleChecker.getInstance().checkRole(user, RoleTypes.ADMIN);
+```
+
+### YAGNI (You Ain't Gonna Need It)
+
+Don't build features, abstractions, or flexibility you don't need **right now**.
+
+```typescript
+// Correct: Solve today's problem
+const formatDate = (date: Date) => date.toISOString().split("T")[0];
+
+// Wrong: Building for hypothetical future needs
+const formatDate = (date: Date, format?: string, locale?: string, timezone?: string) => {
+  // 50 lines handling cases that may never be used
+};
+```
+
+### DRY (Don't Repeat Yourself) - With KISS Constraint
+
+Extract duplication only when:
+1. The same logic appears **3+ times**
+2. The abstraction is **simpler** than the duplication
+3. The extracted code has a **clear single purpose**
+
+### SOLID Principles - Applied Pragmatically
+
+| Principle                 | Apply When                                    | Skip When                               |
+| ------------------------- | --------------------------------------------- | --------------------------------------- |
+| **S**ingle Responsibility | Function does 2+ unrelated things             | Splitting adds complexity               |
+| **O**pen/Closed           | Extension points have clear use cases         | No foreseeable extensions               |
+| **L**iskov Substitution   | Using inheritance hierarchies                 | Using composition (preferred)           |
+| **I**nterface Segregation | Consumers need different subsets              | Interface is already small              |
+| **D**ependency Inversion  | Testing requires mocking external services    | Direct dependency is simpler            |
+
+### Decision Framework
+
+When unsure, ask in order:
+1. **Do I need this now?** (YAGNI) - If no, don't build it
+2. **Is there a simpler way?** (KISS) - Choose the simpler option
+3. **Am I repeating myself 3+ times?** (DRY) - Extract if the abstraction is simpler
+4. **Does this function do one thing?** (SOLID-SRP) - Split only if clearer
+
+---
+
+## Core Principles
+
+### 1. Immutability First
+
+Never mutate data. Always create new references.
+
+```typescript
+// Correct - spread creates new object
+const updated = { ...user, name: "New Name" };
+
+// Incorrect - mutation
+user.name = "New Name";
+```
+
+### 2. Function Structure Ordering
+
+All functions, hooks, and components follow a strict ordering:
+
+```text
+1. Variable definitions and derived state (const, useState, useMemo, useCallback)
+2. Side effects (useEffect, function calls with no return value)
+3. Return statement
+```
+
+### 3. Functional Transformations
+
+Use `map`, `filter`, `reduce` instead of imperative loops and mutations.
+
+```typescript
+// Correct - functional transformation
+const names = users.map(u => u.name);
+
+// Incorrect - imperative mutation
+const names = [];
+users.forEach(u => names.push(u.name));
+```
+
+### 4. Test-Driven Development (TDD)
+
+**Always write failing tests before implementation code.** This is mandatory, not optional.
+
+```text
+TDD Cycle:
+1. RED: Write a failing test that defines expected behavior
+2. GREEN: Write the minimum code to make the test pass
+3. REFACTOR: Clean up while keeping tests green
+```
+
+### 5. Clean Deletion
+
+**Delete old code completely.** No deprecation warnings, migration shims, or backward-compatibility layers unless explicitly requested.
+
+```typescript
+// Correct: Remove the old code entirely
+const calculateScore = (player: Player): number => player.stats.overall;
+
+// Wrong: Keeping deprecated versions around
+/** @deprecated Use calculateScore instead */
+const getPlayerScore = (player: Player): number => calculateScore(player);
+```
+
+**Clean deletion rules:**
+- When replacing code, delete the old version completely
+- Never create `V2`, `New`, or `Old` suffixed functions/variables
+- Never add `@deprecated` comments - just remove the code
+- Never write migration code unless explicitly asked
+- Trust git history for recovery if needed
+
+---
+
+## Quick Reference
+
+### Variable Declaration
+
+| Pattern | Status    | Example                       |
+| ------- | --------- | ----------------------------- |
+| `const` | Required  | `const value = calculate();`  |
+| `let`   | Forbidden | Use ternary or reduce instead |
+| `var`   | Forbidden | Never use                     |
+
+### Array Operations
+
+| Instead of              | Use                                          |
+| ----------------------- | -------------------------------------------- |
+| `arr.push(item)`        | `[...arr, item]`                             |
+| `arr.pop()`             | `arr.slice(0, -1)`                           |
+| `arr.splice(i, 1)`      | `arr.filter((_, idx) => idx !== i)`          |
+| `arr.sort()`            | `[...arr].sort()`                            |
+| `arr[i] = value`        | `arr.map((v, idx) => idx === i ? value : v)` |
+| `forEach` with mutation | `reduce` or `map`                            |
+
+### Object Operations
+
+| Instead of                | Use                           |
+| ------------------------- | ----------------------------- |
+| `obj.key = value`         | `{ ...obj, key: value }`      |
+| `delete obj.key`          | `({ key: _, ...rest } = obj)` |
+| `Object.assign(obj, ...)` | `{ ...obj, ...other }`        |
+
+### Building Lookup Objects
+
+```typescript
+// Correct - reduce with spread
+const lookup = items.reduce(
+  (acc, item) => ({ ...acc, [item.id]: item }),
+  {} as Record<string, Item>
+);
+
+// Incorrect - forEach with Map.set
+const lookup = new Map();
+items.forEach(item => lookup.set(item.id, item));
+```
+
+### Conditional Values
+
+```typescript
+// Correct - ternary expression
+const status = isComplete ? "done" : "pending";
+
+// Incorrect - let with reassignment
+let status = "pending";
+if (isComplete) {
+  status = "done";
+}
+```
+
+---
+
+## Hook Structure Example
+
+```typescript
+export const usePlayerData = (playerId: string) => {
+  // 1. VARIABLES & STATE (first)
+  const [isLoading, setIsLoading] = useState(true);
+  const { data } = useQuery(GetPlayerDocument, { variables: { playerId } });
+
+  const playerName = useMemo(() => data?.player?.name ?? "Unknown", [data]);
+
+  const handleRefresh = useCallback(() => {
+    refetch();
+  }, [refetch]);
+
+  // 2. SIDE EFFECTS (second)
+  useEffect(() => {
+    console.log("Player loaded:", playerName);
+  }, [playerName]);
+
+  // 3. RETURN (last)
+  return { playerName, isLoading, handleRefresh };
+};
+```
+
+## Container Component Example
+
+```typescript
+const PlayerCardContainer: React.FC<Props> = ({ playerId }) => {
+  // 1. VARIABLES & STATE
+  const { data, loading } = useQuery(GetPlayerDocument, { variables: { playerId } });
+  const { colors } = useTheme();
+
+  const formattedStats = useMemo(
+    () => data?.stats?.map(s => ({ ...s, display: formatStat(s) })) ?? [],
+    [data?.stats]
+  );
+
+  const handlePress = useCallback(() => {
+    router.push(`/players/${playerId}`);
+  }, [playerId]);
+
+  // 2. SIDE EFFECTS (none in this example)
+
+  // 3. RETURN
+  return (
+    <PlayerCardView
+      stats={formattedStats}
+      colors={colors}
+      loading={loading}
+      onPress={handlePress}
+    />
+  );
+};
+```
+
+## Utility Function Example
+
+```typescript
+export const calculateTeamRankings = (
+  players: readonly Player[]
+): readonly TeamRanking[] => {
+  // 1. VARIABLES & DERIVED VALUES
+  const validPlayers = players.filter(p => p.team && p.score != null);
+
+  const teamScores = validPlayers.reduce(
+    (acc, player) => ({
+      ...acc,
+      [player.team.id]: {
+        teamId: player.team.id,
+        totalScore: (acc[player.team.id]?.totalScore ?? 0) + player.score,
+        count: (acc[player.team.id]?.count ?? 0) + 1,
+      },
+    }),
+    {} as Record<string, { teamId: string; totalScore: number; count: number }>
+  );
+
+  const rankings = Object.values(teamScores).map(t => ({
+    teamId: t.teamId,
+    avgScore: t.totalScore / t.count,
+  }));
+
+  const sorted = [...rankings].sort((a, b) => b.avgScore - a.avgScore);
+
+  // 2. NO SIDE EFFECTS IN PURE FUNCTIONS
+
+  // 3. RETURN
+  return sorted;
+};
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### Never use `let` for conditional assignment
+
+```typescript
+// Wrong
+let result;
+if (condition) {
+  result = valueA;
+} else {
+  result = valueB;
+}
+
+// Correct
+const result = condition ? valueA : valueB;
+```
+
+### Never mutate arrays
+
+```typescript
+// Wrong
+const items = [];
+data.forEach(d => items.push(transform(d)));
+
+// Correct
+const items = data.map(d => transform(d));
+```
+
+### Never use Map when Record suffices
+
+```typescript
+// Wrong
+const lookup = new Map<string, User>();
+users.forEach(u => lookup.set(u.id, u));
+const user = lookup.get(userId);
+
+// Correct
+const lookup = users.reduce(
+  (acc, u) => ({ ...acc, [u.id]: u }),
+  {} as Record<string, User>
+);
+const user = lookup[userId];
+```
+
+### Never sort in place
+
+```typescript
+// Wrong - mutates original
+const sorted = items.sort((a, b) => a.value - b.value);
+
+// Correct - creates new array
+const sorted = [...items].sort((a, b) => a.value - b.value);
+```
+
+### Never place useEffect before variable definitions
+
+```typescript
+// Wrong
+useEffect(() => {
+  /* ... */
+}, [value]);
+const value = useMemo(() => calculate(), [dep]);
+
+// Correct
+const value = useMemo(() => calculate(), [dep]);
+useEffect(() => {
+  /* ... */
+}, [value]);
+```
+
+---
+
+## Immutable Patterns Reference
+
+### Building Lookup Objects with Reduce
+
+```typescript
+const colorMap =
+  edges?.reduce(
+    (acc, edge) => (edge.color ? { ...acc, [edge.tagId]: edge.color } : acc),
+    {} as Record<string, string>
+  ) ?? {};
+```
+
+### Accumulating Multiple Properties
+
+```typescript
+const teamGprAccumulator = validPlayers.reduce(
+  (acc, player) => {
+    const teamId = player.team?.id;
+    if (!teamId) return acc;
+
+    const existing = acc[teamId];
+    return {
+      ...acc,
+      [teamId]: {
+        teamId,
+        teamName: player.team.name,
+        gprSum: (existing?.gprSum ?? 0) + player.gpr,
+        playerCount: (existing?.playerCount ?? 0) + 1,
+      },
+    };
+  },
+  {} as Record<string, { teamId: string; teamName: string; gprSum: number; playerCount: number }>
+);
+```
+
+### Nested Object Updates
+
+```typescript
+const updated = {
+  ...state,
+  user: {
+    ...state.user,
+    profile: {
+      ...state.user.profile,
+      avatar: newAvatar,
+    },
+  },
+};
+```
+
+### Conditional Property Addition
+
+```typescript
+const result = {
+  ...baseObj,
+  ...(condition && { optionalProp: value }),
+};
+```
+
+### Ternary Chain for Multiple Conditions
+
+```typescript
+const priority = score > 90 ? "high" : score > 70 ? "medium" : "low";
+```
+
+### Readonly Types for Function Parameters
+
+```typescript
+export const calculateTeamGprRank = (
+  leaguePlayers: readonly (PlayerWithScores | null | undefined)[],
+  myTeamId: string | null | undefined
+): number | null => {
+  // ...
+};
+```