Docs & ADRs rules

For changes that affect architecture, data models, external APIs, security posture, deployment topology, or cost (>10%), create an ADR in docs/adr/ using the standard template (Context, Decision, Consequences) and link the PR and issue IDs.

If an API/contract or behavior is breaking, add a 'BREAKING CHANGE' section detailing what breaks, migration steps, and affected consumers.

Add a 'Security & Privacy' section in ADRs addressing threat model impacts, secrets handling, data retention, and PII processing; link to relevant runbooks and DPA if applicable.

Any PR that adds or modifies telemetry/analytics must prove that no PHI leaves the boundary. Use irreversible tokenization or hashing (HMAC with secret salt) for identifiers and document the data dictionary.

Include a 'Rollout Plan' section with phases, feature flags, backout plan, and data migration steps; reference migration scripts and flag names.

Identify functions that raise exceptions but do not document them in docstrings. Missing exception documentation makes it difficult to understand failure cases. Suggest adding an `:raises` section in the docstring.

Emergency access to ePHI must go through a dedicated break_glass path that requires reason, approver, limited time window, and automatic post-incident review. The PR must include changes to the audit log schema and runbook.

If a PR changes an API route/controller signature (path, method, params, request/response schema), update the API specification in the same PR. To enable this check, reference the spec file path in the PR (e.g., `openapi.yaml`, `swagger.json`). If multiple specs exist, update the relevant one. Warn when code and spec drift (new params not documented, status codes changed, response shape changed).

Consent must be stored per user and per purpose with lawful_basis, version, granted_at, source, and optional revoked_at. Do not overwrite or store a single boolean flag. (GDPR Art. 7, purpose limitation)

If a PR adds new PII fields (e.g., email, phone, address, dob, national_id), include links to updated DPIA and RoPA, migration with retention, and masking rules. Add a checklist item confirming lawful_basis. (GDPR Art. 35, Art. 30)

Include Motivation, Approach, Considered Alternatives, Risk & Rollout, and Testing Evidence. Use bullet points; avoid single-line descriptions.

When a PR introduces new PII fields or processing, the PR body must include legal_basis: (e.g., consent, contract) and dpia: (yes/no with link). CI should fail if missing.

Do not rewrite accepted ADRs. When reversing or replacing a decision, create a new ADR with Status: accepted and add 'Supersedes: NNNN' while marking the old ADR as 'Status: superseded by NNNN'.

Every ADR must contain the sections: Context, Decision, Consequences, Status. Allowed Status values: proposed, accepted, deprecated, superseded.

For changes affecting public APIs or modules, include 'Versioning & Deprecation' with semantic version impact and deprecation timeline; link to CHANGELOG and deprecation notices.

Store decision records under docs/adr/ with zero-padded incremental numbering and a kebab-case title: docs/adr/NNNN-title.md (e.g., docs/adr/0001-choose-postgresql.md).

Without ProducesResponseTypeAttribute, Swagger cannot infer the response type of an action returning IActionResult, making API documentation unclear and unreliable.

Provide a short checklist tailored to this change (e.g., 'logic matches spec', 'docs updated', 'flags in place', 'rollback plan noted').

Ensure that all classes, fields, and methods are documented with JSDoc. JSDoc improves code clarity, provides documentation for developers, and helps with IDE autocompletion.

Add a CI job that validates docs/adr/ files: filename pattern, required sections, valid Status, presence of PR/issue links, and optional schema (YAML front matter).

When configuring processors outside the EEA, annotate the config with transfer_mechanism (e.g., SCCs) and link to the signed SCC document; prevent enablement without this metadata. (GDPR Art. 46)

Use `///` for documentation instead of block comments to improve tooling support and ensure better formatting in generated docs.

Include clear, testable success metrics or SLOs in ADRs (e.g., p95 latency < 120ms, error rate < 0.1%) under a 'Measures of Success' section.

All production deployments must reference a change ticket ID, peer approval, and linked rollout plan; write the change_id to the audit log on deploy.