Edit a Large Typed Monorepo Without Breaking Other Packages

## Find the Package That Owns the Change Before Editing Start from the repository root and identify the package that owns the requested behavior. - Distinguish core libraries, framework integrations, deployable applications, examples, and internal tooling. - Read the root guide and the nearest package-level guide; the more specific guide governs package behavior. - Confirm the pinned runtime, package manager, workspace layout, and prerequisite build before running development commands. - Do not assume a root development server exists. Start the owning package or use the workspace filter that includes its upstream dependencies. - Trace shared types, utilities, styles, and generated assets to their canonical package before changing a consumer. - Keep the change in the smallest owning package unless the public contract genuinely spans packages. ## Follow Each Package's Build and Dependency Rules Choose the build path that matches the package rather than forcing one tool across the workspace. - Use a compiler-oriented build for pure typed libraries and a component bundler for UI packages. - Externalize dependencies in library output; use an explicit standalone build only when the deliverable must bundle its runtime dependencies. - Keep internal dependencies on the workspace protocol and source shared third-party versions from the central version catalog. - Import shared types from their documented entry points instead of a broad package root. - When a package publishes multiple formats, verify each declared output and its type declarations. - Treat build configuration, lockfiles, shared compiler settings, and workspace catalogs as broad-impact files that require wider validation. ## Reuse Shared Utilities Before Writing New Code Search the shared helper package before writing a new utility. Check existing array, object, string, URL, HTTP, JSON, Markdown, error, file, queue, formatting, regular-expression, and testing helpers. Reuse a suitable helper directly. Add a new helper to the shared package only when no existing behavior matches and multiple consumers can use the new abstraction. Do not create near-duplicates in feature packages. If existing behavior is close but not exact, compare contracts, edge cases, bundle impact, and call sites before deciding whether to extend it or keep a local domain-specific function. ## Avoid `any` and Type Functions and Component Props Write code that keeps inference useful while making public contracts explicit. - Prefer type aliases and string-literal unions over interfaces and enums when the codebase standard does so. - Give functions explicit return types, use `unknown` rather than `any`, mark type-only imports, and default to immutable bindings. - Keep imports direct; avoid barrel files except deliberate package entry points, and avoid wildcard re-exports. - Never suppress type errors generically. Use an expected-error directive only with a reason that proves the error is intentional. - Handle every promise, and do not mark a function asynchronous unless it awaits work. - In component files, type props and events, destructure defaults, move nontrivial template logic into computed values, and follow the established setup order. - Write comments and API documentation to explain why a constraint exists, not to restate the code. ## Test the Affected Package First, Not the Whole Repo Run the smallest test scope that proves the change. 1. Place unit tests beside their source and name the top-level suite after the file. 2. Prefer behavioral assertions and pure functions; minimize mocks and avoid testing markup structure or styling details when user behavior is the contract. 3. Run the affected package once with an explicit path filter. Use watch mode only during active development. 4. Run integration tests for changed adapters and end-to-end tests for affected user journeys. 5. Start required local test services and wait for readiness before service-dependent tests; unit tests must not use the real network. 6. Run the full monorepo suite only for an intentional final integration check or a broad shared-contract change. Treat unrelated pre-existing failures separately: reproduce them outside the change scope, report them as such, and do not mislabel them as environment success or change-caused failure. ## Lint Changed Files and Type-Check Affected Packages Derive the changed-file set and apply each tool only where it owns the syntax. - Run the typed-language linter and formatter on changed typed files. - Run the component linter and general formatter on changed component, documentation, data, style, and configuration files. - Type-check every affected package through its workspace script. - Scan for unused exports, files, and dependencies before opening or updating a review. - Require all relevant lint, format, type, test, and unused-code checks to pass cleanly. Do not use a whole-repository command when a package filter provides stronger signal with less unrelated noise. Expand validation when foundational configuration changes or when dependency analysis shows multiple downstream consumers. ## Write Review Titles as type(scope) and Add Changesets Use a dedicated branch and conventional, present-tense change descriptions with a relevant package scope. - Give review titles the semantic form `type(scope): subject` using an allowed change type. - Put ticket and issue references in the review description with the correct closing or non-closing keyword; do not bury required tracking identifiers in comments. - Add a dedicated ticket section when tracking links are provided. - For publishable package, integration, or application changes, inspect release-note status and add a patch or minor changeset when a version should move. Do not introduce a major bump through the routine workflow. - Keep temporary workarounds visible with a TODO and explain their removal condition. - Never commit changes with known lint, type, test, or unused-export failures. ## Check UI Changes in the Playground That Shows Them, with Screenshots Build upstream packages, then choose the playground that most directly exposes the changed behavior. - Use the component catalog for base controls, the documentation surface for rendering and navigation, and the client surface for editing, authentication, requests, and responses. - Check secondary surfaces when shared components, themes, syntax rendering, or icons flow into multiple products. - Capture before-and-after screenshots for modified UI, in-context screenshots for new behavior, and a short recording for interactions. - Use descriptive artifact names and embed the evidence in a dedicated visual section of the review description. - If a change affects several surfaces or layouts, capture each materially different result rather than treating one screenshot as universal proof. Visual artifacts supplement automated tests; they do not replace behavioral assertions, accessibility checks, or type validation. ## Use the Project's Exact Terms and Report Only Checks That Ran Use the project glossary consistently in code, documentation, tests, and review text. Distinguish a protocol format from an API description, a data schema from a document, dereferencing from resolving, and bundling from either operation. Before completion: - review the final diff and confirm every changed file belongs to the intended scope; - verify build, tests, lint, format, types, unused-code scan, and visual evidence as applicable; - confirm package entry points, dependency catalogs, and changesets agree with the implementation; - list any check that could not run and preserve its exact failure evidence; - do not claim a full-monorepo result when only a package-scoped check ran. Report the affected packages, commands executed, direct results, residual risks, and any intentionally deferred work.