Build a Data Library with Easy-to-Find APIs and Tests on Real Values

## Hide Complex Source Data Behind Simple Objects Hide source-format complexity behind intuitive domain objects without concealing important capabilities. Make common operations direct, then reveal specialized parsing, reporting, and inspection features progressively when users need them. Read before writing. Before modifying code, inspect the established abstractions, naming patterns, module boundaries, and nearby tests. Extend the existing design unless a concrete incompatibility requires a new pattern. ## Map Which Module Owns Each Job Before Editing Maintain a concise navigation map from user needs to owning modules and key domain classes. Include the public entry points for locating records, loading entities, parsing structured data, building statements, reading notes, opening documents, and constructing typed reports. Trace representative data flows end to end before editing. Follow a request from its public entry point through retrieval, parsing, typed objects, statements, notes, reports, and document extraction. Confirm which layer owns each transformation and where users are expected to drill down for supporting detail. Use the map to select the smallest responsible module. Do not place behavior in a convenient file when another layer already owns that responsibility. ## Read Large Files in Pieces and Keep Edits Narrow Treat modules larger than 30 KB as multiple local contexts rather than reading or rewriting them as one block. Search for the relevant symbol, inspect the enclosing class or function, then read enough neighboring code to understand invariants and call sites. Before changing a large file, locate related tests, imports, subclasses, and public references. Keep the patch narrow, preserve surrounding conventions, and avoid unrelated reformatting or restructuring that would obscure the functional change. ## Record and Update Work in the Issue Tracker Use the project’s issue system as the durable record of active work. Review open and in-progress items, select the relevant issue, and move it to the active state before implementation. Record newly discovered defects or tasks with a clear title, type, and priority instead of leaving them only in comments or chat. Update the same issue when scope, blockers, or conclusions change. Close it only after the required verification is complete. Preserve the defined states for open, in-progress, blocked, and closed work. When the tracker uses a five-level priority scale, keep `0` for critical work and `4` for backlog work rather than inventing ad hoc labels. ## Test That the Library Does What Its Docs Promise Verification asks whether the library delivers what its documentation promises, not merely whether internal code executes. Apply three governing principles: 1. Documentation is the specification, so every documented example must be verifiable. 2. Data correctness is essential, so checks must assert specific expected values rather than mere existence. 3. The API must be solvable, so users and agents must be able to navigate from a question to the appropriate object, method, and supporting evidence. Use these principles to evaluate feature design, documentation, test cases, and failure behavior together. ## Give Each New Feature a Real-Value Test and a Runnable Doc Example Every new user-facing feature must include: - one ground-truth assertion using a specific value from a real source record that has been independently checked; - one documented example that also runs as an automated verification; - one silence check proving that invalid or missing input produces a useful error instead of an empty value or silent failure; - one discoverability update so the feature appears in the project’s navigation, capability catalog, or agent guidance. A feature is incomplete when any of these elements is missing, even if its happy-path implementation works. ## Run Fast Local Tests First and Network Tests One at a Time Provide distinct commands for fast local verification, network-backed verification, regression verification, and coverage reporting. Run the smallest relevant local check first, then broaden only when the focused result passes. Parallelize only fast tests that do not contact external services. Run network verification sequentially and respect service rate limits. Use recorded response fixtures when they can make external behavior fast and deterministic without hiding the contract being verified. Place regressions in a dedicated area with stable names that link each case to its originating defect. Treat coverage as supporting evidence, not as a substitute for assertions about behavior and data. ## Check Exact Values and Clear Errors Across Varied Data Assert exact domain values, normalized structures, and meaningful error messages. An assertion that a result merely exists is insufficient when correctness depends on the value itself. Diversify source records across organizations, industries, formats, and reporting periods instead of relying on one familiar example. Exercise malformed, incomplete, and unsupported inputs explicitly. Confirm that failures return actionable messages and never degrade silently into an empty result. When external data is required, preserve deterministic fixtures and document how their expected values were established. Update a fixture deliberately when the upstream contract changes; do not refresh it merely to make a failing check pass. ## Keep the Version and Docs in Step with Working Code Read the project version from its designated metadata file and avoid duplicating it across unrelated modules. Keep repository navigation, verification guidance, public examples, and capability catalogs synchronized with supported behavior. When an API path changes, update the documentation and executable examples in the same work item. A documented path that no longer runs is a broken user contract even when the replacement implementation is correct.