ipollowork-maintainable-code

# iPolloWork Maintainable Code

Treat this as the repository's single code-quality Skill. Implement changes with the smallest coherent diff, modern platform patterns, bounded runtime cost, and one clear owner. Search and reuse before creating anything.

## Non-Negotiable Outcomes

- **Modern:** use the current repository stack and supported platform APIs; do not add legacy wrappers or compatibility layers without a real supported consumer.
- **Minimal:** solve the requested job with the fewest concepts, files, dependencies, states, and routes that remain clear.
- **Performant:** keep network, database, filesystem, bundle, render, and memory work bounded; optimize measured or structurally obvious hot paths.
- **Reusable:** extend compatible components, hooks, services, schemas, types, and utilities before creating parallel versions.
- **Owned:** keep one source of truth and place behavior in the narrowest existing owner.
- **Clean:** do not create convenience directories, one-off design notes, duplicate implementations, generated source artifacts, or abandoned replacement files.

## Required Workflow

1. Find the repository root. Read `AGENTS.md`, the owning package manifest, the real entrypoint, and nearby implementations.
2. Read `references/repository-boundaries.md` before adding a file, directory, dependency, API, table, or cross-package import.
3. Define a change budget before editing: intended behavior, owning module, expected files touched, and whether any new file, directory, dependency, route, table, or persistent state is truly required. Default every category to zero.
4. Search before creating anything:
   - Search component names, visible labels, route names, event names, type names, and distinctive behavior with `rg`.
   - Search `apps/app/src/components/ui`, `apps/app/src/components`, the target domain, `apps/server/src`, `packages/types`, and `packages/ui` as relevant.
   - Inspect exports and call sites, not just filenames.
5. State the reuse decision: reuse unchanged, extend compatibly, extract for real multiple consumers, or create as the last choice. For each new file or dependency, record why no existing owner can absorb the change.
6. Implement locally. Remove the replaced path in the same change; do not leave `old`, `new`, `v2`, fallback, or dead compatibility copies behind.
7. Add focused tests at the owning layer. Do not duplicate server business logic, contracts, state, or validation in the desktop app.
8. Run the narrow package checks, inspect the complete diff, then run:

```powershell
node .codex/skills/ipollowork-maintainable-code/scripts/audit-changes.mjs
```

9. Resolve every error. Fix warnings or give a concrete ownership/performance reason for keeping the exception.

## Creation Gate

- Add a file only when it has a distinct owner and responsibility that would make an existing file less coherent. A long file alone is not a reason to split it.
- Add a directory only for a real subsystem or package with multiple cohesive files and a stable owner. Never create a directory to hold one small feature, one handoff, one report, or one Markdown note.
- Do not add a new top-level directory without explicit user approval and a repository-level architectural reason.
- Do not create `new`, `old`, `v2`, `copy`, `backup`, `temp`, `tmp`, `misc`, `notes`, `drafts`, `handoff`, or `tdd-summary` paths to avoid integrating with the current owner.
- Do not create a design, plan, QA, summary, or TODO Markdown file for each small feature. Update an existing durable document only when future maintainers need information that code, tests, types, or comments cannot express.
- Add a dependency only when the platform, current dependency graph, and local utilities cannot meet the requirement cleanly. Account for bundle/runtime cost, maintenance, license, and existing transitive capability.
- Do not create a generic abstraction for one caller. Extract only after two real consumers need meaningful shared behavior or centralization prevents contract/security drift.

## Reuse Decision

| Situation | Action |
| --- | --- |
| Existing API/component/helper meets the need | Import and reuse it |
| Existing implementation differs only by presentation or configuration | Add typed props/options without changing existing defaults |
| Two real call sites need the same non-trivial behavior | Extract to the nearest shared owner |
| Similar-looking code has different domain rules or is unlikely to be reused | Keep it local; do not force an abstraction |
| No compatible implementation exists after searching | Create one in the narrowest correct owner |

Do not copy a component and rename it, create `*V2`, `*New`, `*Copy`, or duplicate a helper to avoid understanding its API. Do not add a generic abstraction for a single trivial use.

## Modernity And Simplicity

- Use typed boundaries, functional React, explicit async/error states, semantic controls, and current repository primitives.
- Avoid `any`, broad type assertions, duplicated derived state, prop-to-state mirroring, hidden global state, and fallback branches that types or control flow make impossible.
- Prefer composition and typed options over copied components or mode-heavy forks. Preserve existing defaults when extending shared code.
- Delete obsolete code, exports, dependencies, flags, tests, and documentation when their supported path is removed.
- Keep compatibility only for a named active format, client, or migration window. Document the removal condition beside the boundary.

## Performance Gate

- Keep lists and APIs paginated and bounded. Select only needed fields and avoid N+1 queries, request loops, and repeated filesystem scans.
- Keep React subscriptions narrow. Derive values instead of synchronizing copies, avoid effects for pure computation, and lazy-load genuinely heavy optional surfaces.
- Do not add caching or memoization without a clear owner, invalidation rule, and demonstrated reuse or cost.
- Do not move server-owned data