Skip to content

Audit-driven refactor policy

Branch: development
Status: Active IKaC policy
Related: Source Packet Workflow · Source Evaluation and Evidence Policy · Repository-wide refactor governance · Hypertext & Reciprocity Audit

Repository audits (e.g. hypertext-reciprocity-audit.md, evidence verification audits, layer quality reviews) identify gaps in surfacing, linking, and provenance visibility. They are not new evidence sources. Use this policy when implementing audit recommendations.

Core rule

Audit findings alone are not evidence. Every repository change must be supported by one or more sources already present in the repository or newly captured through the source-packet workflow (sources/inbox/, with provenance in packet metadata).

What to prefer

  1. High-value, low-risk improvements — e.g. inline links where targets exist, DOI citations already in publications.yaml, reciprocal lab links already supported by person_resource_links.yaml or publication_resource_links.yaml.
  2. Surfacing over discovery — make existing YAML, packets, and registry evidence visible on resource pages; do not treat an audit gap as permission to invent facts.
  3. Hypertext connectivity — human-readable markdown links, relationship verbs, reciprocal links where evidence supports bidirectionality.
  4. Evidence visibility — cite DOI, profile URL, evidence_text, or packet path in the same narrative as the link.
  5. Provenance chains — preserve evidence_file, evidence_url, and citation paths from source → checklist → YAML → prose.
  6. Incremental, reviewable diffs — small, page-scoped changes; avoid large-scale rewrites in one pass.
  7. Narrative readability — prose sections remain readable; do not replace narrative with bullet dumps or link lists.

What not to do

  • Do not add new factual claims solely because an audit identified a gap.
  • Do not create relationships from audit symmetry suggestions (e.g. “60 missing reciprocal edges”) without per-edge evidence review.
  • Do not infer collaboration, facility use, or ownership from audit topology alone.
  • Do not edit docs/ (generated mirror); edit resources/ and data/ source-of-truth files only.

Distinguish change types

Report each proposed edit using one or more of:

Type Meaning Example
Knowledge surfacing Evidence already in YAML/registry/packet; now visible in MD PUB-013 DOI added to CSH-018 from publication_resource_links.yaml
Hyperlink improvement Same facts; better navigation Inline link to CSH-001 where ID was plain text
Reciprocal link Return link added where evidence supports A↔B CSH-017 already links CSH-016; add 016→017 if missing
Provenance improvement Same claim; clearer source citation Add packet path or DOI next to existing relationship sentence
New knowledge discovery New claim from a source packet or newly captured material Any layer (people, grants, facilities, …) from packet evidence — not from audit alone

Audit-driven work should be mostly surfacing, hyperlinks, reciprocity, and provenance — not discovery.

Repository-wide rule: Audit implementation does not replace Repository-wide refactor governance. When a packet accompanies audit work, assess all layers; preserve candidates in section M; and run mandatory promotion review on those candidates per the Promotion Discovery Rule, recording the outcome in section N (or an explicit deferral).

Workflow

  1. Read the audit report and cross-check each recommendation against existing sources (YAML evidence_text, publications DOI, packets under sources/inbox/).
  2. Package work in a source packet when new capture or curator rationale is needed; otherwise reference in-repo evidence in refactor_output.md.
  3. Implement incremental diffs; prioritize audit items marked high-value / low-risk.
  4. Produce refactor output (sections A–J) plus the audit implementation summary below.
  5. Stop before commit unless explicitly instructed — human review of diff vs evidence is required.

Audit implementation summary (required when acting on an audit)

Add to refactor_output.md (or section K) when implementing audit recommendations:

## Audit implementation summary

**Audit:** [path to audit report, e.g. docs/reports/hypertext-reciprocity-audit.md]

### Relationships surfaced
- [resource/edge] — evidence: [file or packet path]

### Hyperlinks added
- [from → to] — type: surfacing | navigation | DOI

### Reciprocal links added
- [A ↔ B] — evidence: …

### Evidence used
- [list every source path, YAML record, or packet file supporting changes]

### Recommendations not implemented
- [audit item] — reason: no in-repo evidence | policy (internal grant) | symmetry not evidenced | deferred

Audit report conventions (for future audits)

Future audits under docs/reports/ should:

  • Tag findings high / medium / low value and risk.
  • Separate surfacing opportunities from evidence gaps (needs new intake).
  • Mark items do not implement without new evidence.
  • Link to this policy for implementation rules.

Example: Hypertext & Reciprocity Audit.

Standard sections A–J in Source Packet Workflow still apply. Audit work especially uses:

  • D — New hyperlinks created
  • E — Reciprocal hyperlinks created
  • G — Relationships considered but rejected (include deferred audit items)
  • H — Evidence supporting every accepted relationship

Bottom line

Audits tell you where the map is hard to navigate or under-documented. Refactors surface and link what the repository already knows, cite existing sources, and report what was deliberately left unchanged. Discovery stays in the source-packet workflow.