Surface genealogy

Surface Genealogy

Keep visible product intent recoverable without turning design history into a documentation dump.

Govern the failure seam

Prevent later authors from flattening a deliberate exception, reviving a rejected generic pattern, or mistaking a library default for product identity because the reason for the current surface was absent.

Carry intent in the rendered behavior, implementation, names, and surface constitution first. Record only history, rejection, exception, or constraint that those artifacts cannot explain. Apply this recoverability test to every proposed note:

Could a future reader reconstruct this surface decision from the implementation and constitution in less effort than reading the note?

If yes, omit the note.

Work in this order

1. Discover local authority. Read the repository's surface constitution, component documentation, implementation, tests, history, and existing genealogy format. Preserve the local format when one exists. If none exists, use genealogy-format.md. When the Airworthiness repository assets are available, validate the portable form with its shared schema; a skill-only install still retains the complete behavioral format without claiming schema validation.
2. Separate evidence from intent. Label implementation facts, documented rationale, inference, and unknown history distinctly. Never turn a plausible brand story into recovered history.
3. Assign identity load. Classify each relevant component or pattern as high, medium, or conventional_utility. Concentrate preservation and review on high-identity areas; do not force custom treatment onto utility controls.
4. Record residue only. Capture non-recoverable invariants, allowed variance, rejected options, lineage events, and decisions likely to be incorrectly "cleaned up." Use genealogy-format.md.
5. Expose default debt. Classify retained defaults as accepted, tolerated, unresolved, or scheduled for replacement. The goal is zero unconscious defaults, not zero defaults. Use default-debt-format.md.
6. Preserve exceptions and history. Mark superseded or withdrawn decisions instead of erasing them. Distinguish intentional exceptions and signature asymmetries from unexplained drift. Use exception-and-lineage-format.md.
7. Check the proposed change. Compare it with current invariants, identity load, debt, and exceptions. Escalate unresolved high-identity conflicts; do not silently normalize them.

Audit an inherited surface honestly

• Unify drift only when the active constitution or implementation makes the intended rule recoverable.
• Surface implicit invariants as observations or inferences, not historical fact.
• Mark a cold trail unknown; state what is observable and what cannot be recovered.
• Keep rejected and superseded paths available when they prevent likely regression.
• Delete genealogy prose that merely narrates the current component.

Hold these boundaries

• Do not fabricate operator selections, taste judgments, approvals, or historical rationale.
• Leave operator-owned decisions pending until the operator supplies them.
• Do not treat every inconsistency as error or every default as debt requiring removal.
• Do not let a genealogy note override current executable behavior or a current surface constitution; surface the conflict for resolution.
• Do not require another skill or a particular model, design library, framework, or agent harness.

Compose optionally

Use this skill alone whenever surface lineage is the only concern. It can also supply residue to a surface constitution, inform state review, or give an independent witness the history needed to distinguish convergence from a deliberate utility convention. Companion skills are optional; the local repository remains authoritative.