# Post-Implementation Harness Update Checklist *Use this checklist after any significant feature, refactor, or architectural change to ensure harness documentation stays current.* **Core principle:** Harness doc updates belong in the same PR as the feature. Documentation that drifts from reality is worse than no documentation -- it actively misleads agents. **When to use:** After implementing a feature, completing a refactor, changing architecture, modifying infrastructure, or any change that alters how an agent should understand or interact with the codebase. --- ## Section 1: Change Assessment Identify what changed in this PR. Check all that apply: - [ ] **New modules or directories added.** A new top-level or second-level directory was created, or a new logical module was introduced. - [ ] **Modules deleted or renamed.** Existing directories or modules were removed, merged, or renamed. - [ ] **Dependencies added or removed.** Entries were added to or removed from a `*.csproj`, `Directory.Packages.props`, `package.json`, `requirements.psd1` (PowerShell), or equivalent. - [ ] **Architecture pattern changed.** A structural decision shifted (e.g., moved from REST to GraphQL, adopted a new state management approach, introduced a message queue). - [ ] **New API endpoints or interfaces.** New routes, GraphQL resolvers, gRPC services, or public interfaces were created. - [ ] **Build, test, or deploy commands changed.** The commands a developer or agent runs to build, test, lint, or deploy were modified. - [ ] **New conventions established.** A new coding pattern, naming convention, or structural rule was introduced that future code should follow. - [ ] **Database schema changed.** Tables, columns, indexes, or relationships were added, removed, or altered. - [ ] **Environment variables added or changed.** New env vars are required, or existing ones were renamed or removed. - [ ] **CI/CD pipeline modified.** Workflow files, build steps, deployment targets, or branch protection rules were changed. **Count of checked items: ___ / 10** If zero items are checked, no harness doc updates are needed. If one or more, continue to Section 2. --- ## Section 2: Document Updates by Change Type For each item checked in Section 1, complete the corresponding subsection below. ### If you added new modules or directories - [ ] **.github/copilot-instructions.md** -- Update the project structure / architecture section to include the new module and its purpose. - [ ] **ARCHITECTURE.md** -- Add the module to the domain map and module list. Document its boundaries and dependencies. - [ ] **AGENTS.md** -- Update the structure section if the new module affects how agents should navigate the codebase. - [ ] **Quality grades** -- Add a quality grade entry for the new domain (if using domain-level grading). - [ ] **Spec file** -- Create a specification document for the new module in `specs/` or `docs/`. ### If you deleted or renamed modules - [ ] **.github/copilot-instructions.md** -- Remove or rename the module in the architecture section. Verify no stale references remain. - [ ] **ARCHITECTURE.md** -- Remove the module from the domain map. Update any diagrams or dependency descriptions. - [ ] **AGENTS.md** -- Remove references to deleted modules. Update navigation guidance. - [ ] **Spec files** -- Archive or delete specs for removed modules. Update specs that referenced the old name. - [ ] **All docs** -- Search all markdown files for the old module name to catch stale references. ### If you changed dependencies - [ ] **.github/copilot-instructions.md** -- Update the tech stack table to reflect added or removed dependencies. - [ ] **ARCHITECTURE.md** -- Update the technology decisions section if a significant dependency was swapped. - [ ] **AGENTS.md** -- Update any dependency-specific guidance (e.g., "use X library for HTTP calls, not Y"). - [ ] **Setup instructions** -- Verify install commands still work with the new dependency set. ### If architecture patterns changed - [ ] **ARCHITECTURE.md** -- Update the affected architectural sections. Document the new pattern and the rationale for the change. - [ ] **.github/copilot-instructions.md** -- Update the architecture overview and key data flow sections. - [ ] **Affected specs** -- Update or create specification documents for the new pattern. - [ ] **Quality grades** -- Reassess quality grades for affected domains. - [ ] **AGENTS.md** -- Update agent directives if the pattern change affects how agents should generate code. ### If you added new API endpoints or interfaces - [ ] **ARCHITECTURE.md** -- Document new interfaces in the API surface or data flow section. - [ ] **.github/copilot-instructions.md** -- Update domain concepts if new endpoints introduce new terminology. - [ ] **Spec files** -- Create or update API specs (OpenAPI, GraphQL schema docs, etc.). - [ ] **AGENTS.md** -- Add guidance for implementing against the new interfaces. ### If build, test, or deploy commands changed - [ ] **.github/copilot-instructions.md** -- Update the build and test commands section. This is critical -- agents run these commands directly. - [ ] **AGENTS.md** -- Update verification loop commands if they reference the changed commands. - [ ] **CI config docs** -- Ensure CI pipeline documentation matches the new commands. - [ ] **README** -- Update setup instructions if developer-facing commands changed. ### If new conventions were established - [ ] **.github/copilot-instructions.md** -- Add the new convention to the code conventions section. - [ ] **AGENTS.md** -- Add the convention as an agent directive so agents follow it in new code. - [ ] **ARCHITECTURE.md** -- Document the convention in the relevant architectural section if it is structural. - [ ] **Linter/hook config** -- Consider adding automated enforcement for the new convention. ### If database schema changed - [ ] **ARCHITECTURE.md** -- Update the data model section with new tables, relationships, or indexes. - [ ] **.github/copilot-instructions.md** -- Update domain concepts if new entities were introduced. Update migration commands if the process changed. - [ ] **Spec files** -- Update data model specifications. - [ ] **AGENTS.md** -- Add guidance about the new schema (e.g., "always scope queries by tenant_id"). ### If environment variables changed - [ ] **.github/copilot-instructions.md** -- Update the setup or configuration section with new required env vars. - [ ] **ARCHITECTURE.md** -- Update infrastructure or deployment sections if env vars affect architecture. - [ ] **README** -- Update the environment setup instructions. - [ ] **.env.example** -- Add new variables with placeholder values (never commit real secrets). ### If CI/CD pipeline was modified - [ ] **.github/copilot-instructions.md** -- Update the CI/CD section with new pipeline steps or changed behavior. - [ ] **ARCHITECTURE.md** -- Update deployment architecture if the pipeline change affects how the system is deployed. - [ ] **AGENTS.md** -- Update if CI changes affect how agents should structure their commits or PRs. --- ## Section 3: Validation After making doc updates, verify consistency across all harness documents: - [ ] **File paths are valid.** All file paths referenced in docs point to files that actually exist. - [ ] **Commands work.** All build, test, lint, and deploy commands listed in docs execute successfully. - [ ] **No contradictions.** .github/copilot-instructions.md, AGENTS.md, and ARCHITECTURE.md do not contradict each other on architecture, conventions, or commands. - [ ] **Tech stack is accurate.** The tech stack table in .github/copilot-instructions.md matches actual installed dependencies and their versions. - [ ] **Structure matches reality.** The directory tree in .github/copilot-instructions.md matches the actual project structure. - [ ] **Domain concepts are current.** Terminology definitions reflect the current domain model. - [ ] **Agent directives are actionable.** Every directive in AGENTS.md is specific enough for an agent to follow without ambiguity. --- ## Section 4: Trackability Ensure doc updates are traceable and co-located with the changes that prompted them: - [ ] **Same PR.** Harness doc updates are included in the same pull request as the feature or change. Do not create a separate "update docs" PR. - [ ] **Harness changelog entry.** Add an entry to `docs/harness-changelog.md` describing what was updated and why. - [ ] **Commit message.** The commit message mentions that harness docs were updated (e.g., "add user module; update .github/copilot-instructions.md and ARCHITECTURE.md"). - [ ] **If updates cannot be done now.** Create a tracking issue with the label "harness-docs" and link it to this PR. Include: - Which documents need updating - What changes triggered the need - A deadline (should not exceed one sprint) --- ## Quick Reference: Change-to-Document Matrix | Change Type | .github/copilot-instructions.md | ARCHITECTURE.md | AGENTS.md | Specs | Changelog | |------------------------------|:---------:|:---------------:|:---------:|:-----:|:---------:| | New module/directory | X | X | X | X | X | | Module deleted/renamed | X | X | X | X | X | | Dependency added/removed | X | X | X | | X | | Architecture pattern changed | X | X | X | X | X | | New API endpoint/interface | X | X | X | X | X | | Build/test/deploy changed | X | | X | | X | | New convention established | X | | X | | X | | Database schema changed | X | X | X | X | X | | Env variable added/changed | X | X | | | X | | CI/CD pipeline modified | X | X | X | | X |