research-backlink-detector

Research Backlink Detector

Reads the ## Cross-References section of a target research entry, identifies each cited entry, and appends a reciprocal backlink row to those cited entries. Ensures the cross-reference graph is bidirectionally consistent after the research-cross-referencer post-pass.

Input (from orchestrator prompt):

Add backlinks for ./research/{category}/{name}.md

Output: Each cited entry is edited to include a reciprocal backlink row pointing back to the target entry. The target entry itself is never modified.

Workflow

flowchart TD
    Start([Receive target entry path]) --> ReadTarget[Read the full target entry file]
    ReadTarget --> ParseRefs[Parse Cross-References table using backlink_lib.py<br>parse_cross_references_table]
    ParseRefs --> AnyRefs{Any cross-reference rows found?}
    AnyRefs -->|No rows| Done(["Return STATUS: complete<br>BACKLINKS_ADDED: 0<br>ENTRIES_MODIFIED: none<br>SKIPPED: none"])
    AnyRefs -->|Rows present| ForEach[For each cited entry row]
    ForEach --> ResolvePath[Resolve cited entry path via<br>backlink_lib.py resolve_link_path]
    ResolvePath --> PathExists{Does the resolved path exist on disk?}
    PathExists -->|No — dangling link| SkipDangling["Skip this entry<br>Record in SKIPPED with reason 'path not found'"]
    SkipDangling --> NextRow[Next row]
    PathExists -->|Yes| ReadCited[Read cited entry file]
    ReadCited --> IdempotencyCheck[Check backlink_exists via backlink_lib.py<br>using normalized source link path]
    IdempotencyCheck -->|Already present| SkipDup["Skip this entry<br>Record in SKIPPED with reason 'already exists'"]
    SkipDup --> NextRow
    IdempotencyCheck -->|Not present| Transform[Transform forward description to backlink<br>description via backlink_lib.py<br>transform_to_backlink_description]
    Transform --> BuildRow[Build CrossRefRow with:<br>entry_name = source entry display name<br>link_path = relative path from cited entry to source entry<br>category = source category<br>relationship = transformed description]
    BuildRow --> Append[Append row via backlink_lib.py<br>append_backlink_row]
    Append --> WriteFile[Write updated cited entry to disk]
    WriteFile --> RecordAdded[Record BACKLINKS_ADDED += 1<br>Record cited path in ENTRIES_MODIFIED]
    RecordAdded --> NextRow
    NextRow -->|More rows| ForEach
    NextRow -->|All rows processed| Return([Return structured result block])