Arwp Growth Loop

ARWP Growth Loop

Use this skill when the outcome is not merely “make the site agent-ready” but “improve the site's chances of being discovered, selected, cited or recommended while keeping the work evidence-backed and measurable.”

Product loop

research → classify → technical preflight → internal discovery/demand baseline → hypothesis → implement → verify implementation scope → measure → keep/revert/revise

Do not collapse this into a generic SEO checklist.

Workflow

1. Research before adding a tactic. Start with:

node bin/arwp-trends.mjs list --since=90 --exclude-retired
node bin/arwp-hypotheses.mjs list --vertical=general

When network access exists, review current primary sources for the target surfaces. Prefer official platform documentation and specifications. Classify a mechanism as platform requirement, platform guidance, platform feature, platform measurement, or project experiment. Newness alone is not evidence.

For page-level structured data, identity, canonicalization, authorship, events, datasets, localization or terminology, load registry/page-semantics-profiles.json (or the published recommendations/page-semantics.json). Treat it as an implementation-routing profile, not as a ranking hypothesis.

2. Establish the site baseline and run Technical Integrity. Inspect framework, deployment, public root, routes, content architecture, metadata, sitemap/robots, structured data, images/video, crawler policy, existing agent surfaces and owner-side metrics where available. Then run both:

node bin/arwp.mjs technical-integrity https://example.com/ --max-pages=20 --max-link-targets=24 --json
node bin/arwp-growth.mjs https://example.com --vertical=<vertical> --json

Technical Integrity is the bounded preflight for problems that can already be checked before Search outcome windows mature. It evaluates provider/source-backed technical blockers and conservative review heuristics including:

• robots.txt fetch semantics and path-specific Googlebot access on sampled priority URLs;
• known HTTP/noindex failures;
• Google AI snippet restrictions;
• canonical integrity on HTML pages only;
• bounded retrieval-footprint outliers without relabeling audit limits as Search failures;
• soft-404 suspicion;
• crawlable internal-link markup plus a capped health probe of important same-origin link targets;
• raw textual availability and JS-shell risk;
• hreflang reciprocity;
• Bing preview/grounding controls;
• near-duplicate priority content;
• OAI-SearchBot policy separately from GPTBot training policy.

Internal-link target probing is intentionally bounded. By default Goose selects at most 24 same-origin targets from the priority cohort, favoring links referenced from more sampled pages, then more occurrences and shallower paths. 404, 410 and 5xx targets make this P1 check fail; redirects, authorization/rate-limit states and probe uncertainty remain WATCH. A redirect is not automatically harmful, and the sample is not a claim about every internal link on the site.

Interpret states strictly:

• FAIL — a bounded source-backed blocker or explicit broken technical target was actually observed; fix or deliberately resolve it before optional acquisition work when material;
• WATCH — investigate context/rendering/redirects/audit limits; it is not automatically a defect;
• PASS — no issue was observed by that detector in the bounded sample; it is not ranking/indexing proof;
• not-applicable — the check does not apply to the observed representation.

A bounded fetch failure is unknown, not an indexability failure. A directly served Markdown/text resource is not required to carry an HTML <link rel="canonical">. Do not weaken these truth boundaries to make the report look cleaner.

Do not infer Google/Bing/ChatGPT visibility from repository metadata or from a green technical preflight.

Internal discovery before content expansion

For multi-page sites, data sites, documentation, editorial resources, entity directories or any task involving internal links/hubs/topic clusters, run the bounded Internal Discovery evidence graph after hard eligibility blockers are understood and before approving broad URL/content expansion:

node bin/arwp-internal-discovery.mjs https://example.com/ \
  --max-pages=20 --json --output=internal-discovery.json

Read docs/INTERNAL-DISCOVERY-EVIDENCE.md. Use the report to review:

• canonical owners with no observed inbound owner path in a complete bounded cohort;
• owners reached only by global navigation when an in-context relationship would genuinely help users;
• owners with no contextual/hub/utility continuation when the page is not intentionally terminal;
• links that still point at sampled redirects, canonical aliases or non-indexable states rather than stable canonical owners;
• unknown or out-of-cohort edges that need more evidence before action.

The analyzer classifies raw-HTML link placement conservatively as contextual, hub, utility, global or unclassified. Those are Goose review heuristics, not Google ranking categories. Never produce PageRank/authority/SEO scores from this graph. Never add sitewide/footer links merely to improve a count.

Coverage is part of the result. If any canonical owner reaches the per-page anchor observation cap, gapEvaluationState=partial; inbound/global-only gaps that could be falsified by omitted edges stay suppressed. Preserve that unknown state instead of calling pages orphaned.

When JavaScript rendering materially changes the graph, use rendered/browser evidence or a deterministic inspected build artifact; do not treat raw source or a stale build as conclusive runtime graph evidence.

Freshness integrity only when two revisions exist

Do not infer truthful sitemap freshness from a one-shot crawl or from the mere presence of <lastmod>. When the task involves sitemap-date automation, repeated deployments, freshness drift, large data sites, or a before/after repository change and two comparable revisions are available, read docs/FRESHNESS-INTEGRITY.md and build revision-bound snapshots:

node bin/arwp.mjs freshness snapshot \
  .arwp/site-state-before.json sitemap-before.xml \
  --output=freshness-before.json

node bin/arwp.mjs freshness snapshot \
  .arwp/site-state-after.json sitemap-after.xml \
  --output=freshness-after.json

node bin/arwp.mjs freshness compare \
  freshness-before.json freshness-after.json \
  --output=freshness-comparison.json

Use Freshness Integrity only as longitudinal implementation evidence:

• lastmod-churn-candidate means the sitemap date moved while every currently mapped route input stayed byte-identical; same-commit churn is the strongest review case for build/deploy-time dates;
• stale-lastmod-candidate means a mapped owner/template/build input changed while the date did not, but source change is not proof of a significant page change, so review the diff and rendered page before touching the date;
• aligned-change means date and mapped inputs both moved, not that the date is necessarily justified;
• unknown stays unknown when route ownership, mapped inputs or valid W3C <lastmod> evidence is incomplete.

Never derive <lastmod> from file mtimes, build timestamps, deployment timestamps or the current clock. Never mass-refresh dates to satisfy the tool. A runtime/CMS change outside Repository Mapper can legitimately explain a date change; improve evidence coverage rather than forcing the target site to match an incomplete repository model.

Verify treatment scope before interpreting outcomes

When a growth experiment or before/after analysis is route-scoped and both before/after Repository Mapper Site State Graphs exist, read docs/TREATMENT-COHORT-INTEGRITY.md and compare the implemented route scope before interpreting Search/AI/referral/business movement:

node bin/arwp.mjs treatment-cohort compare \
  .arwp/site-state-before.json \
  .arwp/site-state-after.json \
  --treatment=treatment-urls.json \
  --output=treatment-cohort.json

Use this as companion implementation evidence, not as a replacement for the Growth Experiment record.

Review these states before outcome interpretation:

• declared-treatment-unchanged — a planned treatment URL has byte-identical complete mapped inputs; verify that the implementation actually reached it or that a missing runtime source explains the treatment;
• declared-treatment-unknown — the intended treatment cannot be proven from complete comparable source ownership; resolve evidence before presenting it as implemented;
• changed-outside-treatment — shared layout/template/data/metadata changes affected canonical routes outside the declared cohort; expand the treatment, isolate the implementation, or explicitly mark the experiment contaminated;
• mapping-basis-changed — adapter/site-root changed, so the route-level comparison fails closed and should be treated as a separate migration event;
• same-commit-drift — the same immutable Git commit is associated with different mapped inputs, so dirty/stale/inconsistent snapshots are unknown, not treatment evidence.

The actual changed cohort includes mapped changed, added and removed canonical routes. Route evidence includes the document owner, buildPath and resolved route-scoped surface owners, so a shared template can correctly expand the actual cohort beyond the page whose leaf source was edited.

Do not shrink the actual cohort to preserve a cleaner experiment story. Digest movement proves implementation-input movement only; it does not prove a visible/significant page change or causal effect.

When page semantics are relevant, inventory the important route archetypes and identify reusable canonical entities before editing templates. Classify pages such as site-home, organization, article-editorial, author-profile, event, dataset, software-application, product, video-watch, glossary-term/glossary-index, community-qa and collection-list. Do not install a universal JSON-LD bundle.

For portfolio or repeated site rollouts, follow docs/SITE-ROLLOUT-PLAYBOOK.md and start a site-specific record from templates/growth/site-adoption-record.md. Reuse the decision order and evidence contract; do not blindly copy provider-specific markup or crawler policy from a reference site.

3. Select hypotheses, not cargo cult. Choose the smallest applicable hypothesis set that has a clear implementation change, checkable completion condition and observable success signal. Platform requirements and high-confidence guidance come before optional features or experiments.

Structured-data correctness is a baseline contract, not an excuse to maximize schema volume. Remove obsolete feature-only markup when appropriate and never fabricate authors, dates, prices, ratings, reviews, event facts, organization facts or dataset provenance.

4. Implement highest-confidence changes. Typical order:
   • Technical Integrity FAIL blockers and reviewed high-impact WATCH findings;
   • broken important internal-link destinations observed by the bounded target-health check;
   • reviewed Internal Discovery P1 missing-path findings and clearly useful canonical transition cleanup;
   • Search/AI/Discover eligibility blockers;
   • canonical URLs, sitemap and meaningful freshness;
   • canonical/sitemap/indexability consistency and reciprocal/self hreflang for real localized variants;
   • non-commodity content and original evidence;
   • resolvable identity, authorship and provenance;
   • stable WebSite/publisher/author/product/dataset/term identities and page-specific JSON-LD grounded in visible first-party facts;
   • unique useful event leaf pages for real events when targeting event features;
   • real Dataset provenance and DefinedTerm/DefinedTermSet graphs where the site's content model actually contains them;
   • useful contextual/hub/action internal links justified by actual user journeys, not graph-volume targets;
   • deep-linkable sections;
   • relevant large images/video when a target surface benefits;
   • Preferred Sources or other bounded acquisition features when applicable;
   • snippet/AI-preview controls only when they match publisher policy;
   • crawler/freshness mechanisms that match publisher policy;
   • agent interoperability only for real agent use cases.

For each material route-level change, record problem → evidence → risk → recommendedChange → files → autofix → verification → source. Autofix only when the required facts already exist. Otherwise leave an explicit owner-data gate.

5. Verify. Run the site's own build/tests/lint, Technical Integrity again on the deployed/public surface when network access exists, and relevant ARWP checks. For each selected hypothesis, distinguish pass, fail, manual-pass, manual-fail, external-owner-data, not-applicable and watch. Never call a manual or owner-data check automated.

For semantic/template changes also parse generated JSON-LD, compare it with the rendered visible content, and check canonical/indexability/sitemap/hreflang consistency on changed routes. Use current feature-specific external validators or Search Console/Bing tools where owner access exists.

For internal-link/hub changes, rerun the same bounded Internal Discovery cohort when practical. A cleaner graph verifies the implementation only; Search impressions, positions, citations, referrals and conversions remain separate outcome evidence.

For sitemap freshness automation or meaningful date-policy changes, compare the before/after Freshness Integrity snapshots when both revision-bound Site State Graphs exist. A clean comparison verifies only mechanical date/source coherence. It does not prove significant content change, recrawl, indexing, ranking or traffic effects.

For route-scoped experiments, run Treatment Cohort Integrity after the implementation and before outcome interpretation when comparable before/after Site State Graphs are available. If mapped changes exist outside the declared treatment, do not silently attribute the full outcome window to the declared URLs; expand/isolate the cohort or mark contamination explicitly.

Technical Integrity is intentionally self-correcting. If a live dogfood run exposes a false positive caused by an audit limit, representation mismatch or detector assumption, fix the detector/evidence model rather than editing the target site to satisfy a bad check.

6. Measure. Where owner data exists, compare the relevant Google Search/generative/Discover signals, Bing AI citations and grounding-query samples, ChatGPT referral traffic/citations, image/video discovery, conversions and agent task completion. Choose a sensible before/after window. Do not automatically attribute movement to ARWP.

Before interpreting route-scoped outcome movement as evidence for the selected treatment, confirm that the companion Treatment Cohort Integrity report is either clean enough for that scope or explicitly records contamination/unknown coverage. A treatment-scope pass is still not causal attribution; seasonality, demand shifts, competitors, indexing timing and other concurrent changes remain possible explanations.

7. Keep, revise, revert or retire. Preserve negative results. Keep a correct change when evidence is neutral/positive, revise a weak implementation or measurement design, revert harmful changes, and retire a hypothesis when upstream guidance or evidence invalidates it.

Use templates/growth/growth-loop-checklist.md, templates/growth/site-adoption-record.md and templates/growth/hypothesis-ledger.md when a durable review trail is useful.

Core rule

ARWP never guarantees ranking, Discover placement, AI citation, recommendation traffic or conversion. The goal is faster adaptation, stronger implementation discipline and better evidence about what works for the actual site.

Search opportunity selection

After eligibility fixes and relevant Internal Discovery review, read docs/SEARCH-OPPORTUNITIES.md. Build a small reviewed map of real user needs, existing landing pages, original assets and useful next actions. Prefer improving a complete existing answer to generating pages for query variants.

node bin/arwp-opportunities.mjs templates/growth/arwp-opportunity-map.json
node bin/arwp-opportunities.mjs <site-map.json> --search-console=<private-query-page.json> --json

The bundled map is a self-pilot with hypothetical queries and no verified demand. Adapt it only after inspecting the target repository. Joint final query+page data is required for owner-observed prioritization; separate Queries and Pages exports or aggregate visibility snapshots cannot be joined into that evidence. Missing data stays unknown. Keep real exports and reports private.

Use the queue as a project heuristic, not a ranking score. Review overlapping URLs manually; do not automatically merge, redirect or noindex. Verify that declared original assets and internal links actually exist. Implement one substantive useful improvement, verify the built page and next action, record its commit, then use the existing experiment/visibility workflow for outcomes. Do not replace the live Growth audit or the owner-measurement gate with this offline planner.

Search appearance review

After building relevant HTML, run the explicit local check and read docs/SEARCH-APPEARANCE.md:

node bin/arwp-search-appearance.mjs <built-page.html> \
  --url=https://example.com/ --output=appearance.json

Use the actual public URL represented by that file. A project or locale subdirectory does not have separate Google site-name or Search-favicon scope. Never overwrite hostname-wide branding during a project rollout. Inspect existing WebSite nodes, preserve conflicting identity evidence, and check genuine alternate names before adding markup. Review malformed JSON-LD even on non-root pages.

The report is static evidence, not a rendered-DOM, image-byte, robots or Search-appearance validation. Keep absent/unsupported declarations distinct from failed checks and actual outcomes. This command is not yet automatically invoked by the live arwp-growth audit. Carry its review actions into the site's adoption record explicitly, and retain owner-side appearance observation as a separate follow-up.

When a Search Appearance finding is accepted and a repository change is actually being prepared, combine it with an existing Repository Mapper Site State Graph instead of guessing the source file:

node bin/arwp-search-appearance-patch.mjs build \
  appearance.json .arwp/site-state.json \
  --output=appearance-patch.json

The patch manifest is proposal-only. It records exact mapped source ownership and beforeSha256 only when ownership is proven. buildPath alone is not field ownership. Unknown site-name state remains absent rather than becoming a patch request; ambiguous framework ownership remains manual; project-subdirectory hostname branding stays blocked. A patch manifest never authorizes a target-repository write by itself.

Concrete implementation practices

After identifying the site gap, use arwp-discoverability or arwp discoverability --search="comparison" --json to inspect concrete practices. The corpus adds implementation choices to existing hypotheses and rules; a routing reference does not establish applicability or an outcome. Read the current native registry entries, select a few relevant IDs and carry accepted work through this Growth Loop, the site adoption record, Growth experiment and shared BraidGraph.