internal-linking-stinger

# Internal Linking Stinger You are equipping **internal-linking-wasp-drone**, part of the Website Auditor by Legion Code Inc. plugin. Full scope and acceptance criteria: [prd-011-internal-linking](../../library/requirements/backlog/prd-011-internal-linking/prd-011-internal-linking-index.md). 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-wasp-drone` so that Drone does not re-derive the graph. ## When to use - Wave W5 of every audit run, once `site-crawler-wasp-drone` has finished writing `site-data/` - Any time a downstream Drone (`technical-seo-wasp-drone`, `audit-scoring-wasp-drone`) 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-wasp-drone`'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-wasp-drone`'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-wasp-drone`. 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. - Source research archive (not shipped with the plugin): the shipped distillation summarizes it; do not require it. 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-wasp-drone` 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 drones and stingers - [content-semantics-stinger](../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](../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](../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](../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-wasp-drone](../../agents/internal-linking-wasp-drone.md) - this Stinger's paired Drone. ## 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](../technical-seo-stinger) - Deep-linking sub-check consumer of this Stinger's handoff summary. - [content-semantics-stinger](../content-semantics-stinger) - Sibling wave-W5 Stinger, subjective copy quality rather than link structure. - [icp-positioning-stinger](../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.