Internal Linking Stinger

Internal Linking Stinger

Forge status: stages 1-6 complete (Topic, Research, Distillation, References, Guides, final authorship). Stage 7 (registration/deployment sync) has not run. Every factual claim below traces to references/research/raw/ via the distillation at references/research/distilled-internal-linking.md; the two structural exceptions are the composite anchor-scoring weights and the URL-to-slug matching heuristic in references/scripts/link-graph.py, both explicitly flagged as this Stinger's own engineering judgment calls in that script's docstring, not sourced numbers.

You are equipping internal-linking-worker-bee, part of the Website Auditor by Legion Code Inc. plugin. Full scope and acceptance criteria: prd-011-internal-linking.

This pair's research archive is unusually deep for this plugin: five raw sources specifically on link-graph mechanics (graph-theoretic methodology, a practitioner audit checklist, PageRank-mechanics worked math with concrete thresholds, and an anchor-text-quality rubric), plus two tangential sources retained for narrow, explicitly-scoped relevance. Use that depth. Do not fall back to generic "check your internal links" advice when the archive gives you BFS mechanics, a real power-iteration formula, and a four-dimension anchor rubric to apply instead.

Purpose

Build a directed internal link graph from site-data/ (already crawled, read-only) and produce the run's 03-seo/internal-linking.md sub-audit: which pages are orphaned, how many clicks from a defined entry-point set every page sits at, how strong each page's inbound anchor-text signal is (and whether any anchor text is cannibalized across destinations), and how link equity is structurally distributed across the site via an internal-PageRank-style proxy. Also produces a short deep-linking handoff summary for technical-seo-worker-bee so that Bee does not re-derive the graph.

When to use

• Wave W5 of every audit run, once site-crawler-worker-bee has finished writing site-data/
• Any time a downstream Bee (technical-seo-worker-bee, audit-scoring-worker-bee) needs a link-graph fact and should read this Stinger's output rather than re-deriving it
• Diagnosing why an important page is not ranking or not getting indexed when the cause might be structural (buried too deep, orphaned, starved of equity) rather than a content problem

When not to use

• Crawling the site or fetching a page not already in site-data/. This Stinger never crawls; that is site-crawler-worker-bee's job (PRD-007). A link pointing outside site-data/ is reported as external or uncrawled, never fetched.
• Judging copy quality, reading level, or ICP relevancy of a page's content. That is content-semantics-stinger's scope.
• Judging external backlink profile or off-site authority. The equity computation here is internal-graph-only by construction (see guide 4); it explicitly excludes external backlinks.
• Re-deriving the full internal link graph inside technical-seo-worker-bee's deep-linking sub-check. Read this Stinger's handoff summary instead.

Procedure

1. Confirm site-data/ is populated (read-only), then build the graph and compute every metric in one deterministic pass via references/scripts/link-graph.py. See guides/01-graph-construction-and-orphan-detection.md.
2. Cross-reference the script's orphan candidates against every other known-URL source available to the run and classify each by reachability state before recommending a fix; report dead-ends as a separate, less severe finding. See guides/01-graph-construction-and-orphan-detection.md.
3. Define the entry-point set explicitly (never homepage-only by default) and interpret the BFS click-depth output, including path diversity and unreachable pages, against the site's own navigation philosophy. See guides/02-click-depth-bfs.md.
4. Score every page's inbound anchor-text profile across the four cited dimensions (generic ratio, diversity, topical relevance, length), both all-inbound and contextual-only, and resolve any anchor-text cannibalization found. See guides/03-anchor-text-scoring.md.
5. Interpret the internal-PageRank-style equity distribution: classify every page, compute the Gini-coefficient distribution shape, and state the computation's explicit boundary (no external backlinks, no link-context quality, no history, not Google's real ranking layers) every time this section is used. See guides/04-link-equity-pagerank.md.
6. Assemble 03-seo/internal-linking.md from references/templates/internal-linking-report-template.md, fill the findings-register rows with the mandatory numeric value, evidence pointer, and one-line justification per row, log any rejected/reframed candidate, and produce the deep-linking handoff summary for technical-seo-worker-bee. See guides/05-report-assembly-and-handoff.md.

References map

• references/research/distilled-internal-linking.md, load when a claim needs verification, a specific threshold's provenance needs checking, or a dispute needs settling. This is the single most load-bearing file in this Stinger; it names exactly which numbers are single-vendor heuristics versus corroborated across sources.
• references/research/raw/, load when tracing a distilled claim back to its primary source, or when the distillation's citation feels thin and you want the original context.
• references/scripts/link-graph.py, run once per audit after site-data/ is complete; do not hand-compute BFS depth, anchor scores, or PageRank-style equity, this script exists so those numbers are reproducible. Its docstring carries the full grounding note per number it produces, including which two things (composite-score weights, URL-to-slug matching) are this Stinger's own judgment call rather than a sourced figure.
• references/templates/internal-linking-report-template.md, load when assembling 03-seo/internal-linking.md; mirrors the script's JSON output field for field.
• references/templates/edge-record-template.md, load when inspecting or hand-verifying a specific edge rather than the full graph.
• references/templates/deep-linking-handoff-summary-template.md, load when producing the summary technical-seo-worker-bee reads instead of re-deriving the graph.
• guides/01-graph-construction-and-orphan-detection.md through guides/05-report-assembly-and-handoff.md, load in order for a full pass; each maps to one section of the report template.

Related bees and stingers

• content-semantics-stinger - Subjective copy interpretation and reading-level scoring for the same crawled page set. Runs alongside this Stinger in wave W5; the two do not overlap in scope (content quality vs. link structure) and neither duplicates the other's output.
• technical-seo-stinger - Owns the run's broader technical-SEO sub-audit, including a deep-linking sub-check that reads this Stinger's handoff summary rather than re-deriving the graph.
• icp-positioning-stinger - Owns the run's ICP and conversion-action taxonomy, referenced (not duplicated) when this Stinger judges which under-served pages are "important per strategy" in the equity-flow section.
• site-crawler-stinger - Produces the site-data/ this Stinger reads read-only. This Stinger never crawls; if site-data/ is incomplete or missing, that is a site-crawler dependency gap, not something to work around here.
• internal-linking-worker-bee - this Stinger's paired Bee.

Critical Directive

• You must read all files and context contained within your skill.
• In the event your core knowledge does not provide sufficient guidance you must make every attempt to search the internet, related knowledge base documentation files, and other available resources to supplement your knowledge prior to proceeding with your task.
• Additional related skills can be found here:
  • technical-seo-stinger - Deep-linking sub-check consumer of this Stinger's handoff summary.
  • content-semantics-stinger - Sibling wave-W5 Stinger, subjective copy quality rather than link structure.
  • icp-positioning-stinger - ICP and conversion-action taxonomy referenced when judging "important per strategy" pages.

Ship Gate

Ship Gate removed: research-only stinger, produces no committable code. This Stinger's output is a findings report (03-seo/internal-linking.md) written to the target audit workspace outside this repository; it never proposes a diff or a commit to this plugin's own tracked source, so the security-stinger / quality-stinger / github-repo-health-stinger close-out sequence does not apply.