website-analysis

name	website-analysis
description	Creator-first website analysis skill. Dual-lens (Creator View + Engineer View) three-tier (Quick/Standard/Deep) analysis of arbitrary websites with superpowers-chrome extraction, compliance gates, and multi-mode operation (Page/Site/Expedition/Cross-site).

Document Version: 2.0 Last Updated: 2026-04-15 Status: ACTIVE

Shared conventions: See .claude/skills/shared/CONVENTIONS.md

/analyze router: This skill is the website-handler arm of /analyze — direct invocation and router dispatch both supported. Handoff contract: the router passes {target, auto_detected_type: "website"} as if the skill were invoked directly.

Website Analysis

Creator-first analysis of websites as knowledge artifacts. Mirrors /repo-analysis architecture but designed for web content — what a site KNOWS, ARGUES, and LINKS TO.

Warm-up (shown at invocation)

/website-analysis <URL> [--mode=page|site|expedition] [--depth=...]
  mode:          page (default) | site | expedition | cross-site
  depth:         quick | standard (default) | deep
  phases:        PHASE N of M  (M = 6 Standard / Deep; 1 Quick; variable Expedition)
  est. time:     Quick ~30s | Standard 2-4m | Deep 5-10m | Expedition open-ended
  output:        .research/analysis/<site-slug>/
  prior feedback: {replay per CONVENTIONS §18 if prior state file exists}

Routing Guide

You want to…	Use this
Analyze one website / page	/website-analysis (here)
Let router auto-pick repo vs site vs PDF	/analyze <target>
Cross-site synthesis across 3+ analyses	/synthesize
Test OUR webapp (local)	/webapp-testing
Library / package documentation	context7 MCP
Domain / technology research (query-driven)	/deep-research

Critical Rules (MUST follow)

1. Compliance check before ANY extraction. Pre-flight runs first. HARD_BLOCK stops the skill with a minimal analysis.json explaining why.
2. superpowers-chrome is primary extractor. If unavailable, fall back to WebFetch + Playwright MCP + curl. Log a warning.
3. Write-to-disk-first. Every phase writes output before proceeding. Do not hold results in memory across phases.
4. State file on every phase transition. Update .claude/state/website-analysis.<site-slug>.state.json after each phase.
5. Creator View is mandatory for Standard/Deep. Written as conversational prose, NOT tables or clinical output.
6. No silent skips. If a SHOULD step fails, retry once, then report.
7. Bands over numbers. Display categorical bands with scores in parens.
8. Home context MUST be loaded for Creator View — SESSION_CONTEXT.md, ROADMAP.md, CLAUDE.md, .claude/skills/, MEMORY.md user entries.

When to Use

• User provides a URL and wants to understand what the site knows
• Domain/technology scouting (JASON-OS Domain 02a)
• Evaluating a website as a knowledge source for ongoing work
• Comparing a site's perspective to our documented approach

When NOT to Use

• Testing OUR webapp → /webapp-testing
• Package docs → context7 MCP
• Simple URL fetch → WebFetch
• GitHub repo → /repo-analysis
• Cross-site synthesis → /synthesize
• Topic research → /deep-research

Input

/website-analysis <URL>                        # Page mode, Quick Scan default
/website-analysis <URL> --depth=standard       # Standard depth
/website-analysis <URL> --depth=deep           # Deep depth
/website-analysis <URL> --depth=quick          # Explicit Quick Scan
/website-analysis --urls=URL1,URL2,...         # Site mode, explicit pages
/website-analysis <URL> --site                 # Site mode, auto-discovery
/website-analysis <URL> --expedition           # Expedition mode (HITL)

Re-invoking with the same URL auto-resumes from last completed phase.

Output

.research/analysis/<site-slug>/ produces these artifacts:

Artifact	Phase	Format / Notes
analysis.json	0+	Core record (schema v3.0)
meta.json	0	Metadata snapshot (handler-specific)
findings.jsonl	2/3	One JSON object per line
creator-view.md	2	Conversational prose, 7 sections
summary.md	3	Health bands
value-map.json	4	Knowledge candidates ranked
deep-read.md	1b	Multi-page only
content-eval.jsonl	2	One entry per evaluated link
coverage-audit.jsonl	pre-audit	Unexplored items + user decisions
extraction-journal.jsonl	routing	Append-only cross-source record

Full schemas in REFERENCE.md §1.

---

Process Overview

VALIDATE      URL valid? Prior analysis? Tool check? Prior feedback replay (§18)?
PREFLIGHT     Compliance (robots.txt, cf-mitigated, RSS, HARD_BLOCK/WARN/PROCEED)
PHASE 0 of M  Quick Scan (navigate + eval + screenshot analysis)
GATE          Interactive "Run Standard/Deep?" — flags bypass
PHASE 1 of 6  Content extraction (WebFetch processed content)
PHASE 1b of 6 Multi-page (replaces Phase 1 in Site/Expedition mode)
PHASE 2 of 6  Creator View (7 sections, home context, 13 value axes)
PHASE 3 of 6  Engineer View (6 dimensions, 4-band scoring)
PHASE 4 of 6  Value Map (knowledge candidates ranked)
SELF-AUDIT    Verify artifacts, schema, completeness (9 dimensions)
ROUTING       Menu (7 options)

M = 1 for Quick Scan only, M = 6 for Standard/Deep, variable for Expedition. Phase markers: ========== PHASE N of M: [NAME] ==========

---

Compliance Pre-flight (MUST — runs before extraction)

1. Fetch robots.txt via WebFetch (cache for session)
2. Check Anthropic user agents (ClaudeBot, Claude-User, Claude-SearchBot)
3. Check cf-mitigated header — WARN if Cloudflare detected
4. Check for RSS/Atom feeds — surface as option if found
5. Check X-Robots-Tag headers
6. Classify: HARD_BLOCK | WARN | PROCEED
7. HARD_BLOCK → minimal analysis.json with compliance reason, stop.
8. WARN → surface to user, require acknowledgment before continuing.

Done when: compliance status written to analysis.json AND either PROCEED path taken OR HARD_BLOCK recorded.

Full robots/UA handling, feed discovery, and error triage — REFERENCE §7.

---

Extraction (Phase 1 of 6 / 1b of 6)

Primary (superpowers-chrome available): use_browser navigate → use_browser eval → WebFetch → curl -sI (Deep).

Fallback (no superpowers-chrome): WebFetch → Playwright navigate + run_code → curl -sI (Deep).

Multi-page (1b): Site or Expedition mode; extract per discovered/listed URL, aggregate into deep-read.md.

Done when: raw extraction artifacts exist per analyzed URL AND content-eval.jsonl seeded from outbound-link scoring.

---

Modes

Mode	Flag	Default behavior
Page	(default)	Single URL; all three depths available
Site	--site	Auto-discovery from root + top-scored internal links
Site	--urls=...	Explicit URL list; no per-page gates
Expedition	--expedition	HITL multi-hop (5-option gate per hop)
Cross-site	(routing only)	Offered at routing menu if 3+ sites analyzed

Site-mode scope-explosion soft prompt: At >50 pages (auto-discovery or explicit list), pause and prompt: "Site scope reached N pages. Continue / Limit to first 50 / Stop?" User decides; never hard-block.

Auto-discovery 5-page gate: No hard cap. Pause every 5 pages showing themes / links scored / knowledge candidates. User continues or wraps up. At page 20+, advisory: "Extensive coverage reached."

Full mode specs: Site → REFERENCE §11, Expedition → REFERENCE §10.

---

Quick Scan (Phase 0 of M)

Runs on every invocation. Produces metadata snapshot, structural counts, screenshot analysis (SHOULD), compliance status, absence-pattern detection (detectable at Quick tier), lightweight Creator View teaser (2-3 sentences).

Writes: meta.json, analysis.json (Quick tier). Write to disk before gate.

Gate: Quick Scan is a preview — not a peer user tier. Standard produces the full artifact set needed for /synthesize cross-source intelligence. Prompt: "Run Standard? (~5-10 min) [Y/n]". All depth / mode flags bypass this gate.

source_tier: Websites span T1-T4 based on editorial authority. Default T2; handler may suggest a different tier from content signals.

Done when: meta.json AND partial analysis.json exist; creator-lens teaser written.

---

Creator View (Phase 2 of 6 — MUST for Standard/Deep)

Seven sections, conversational prose. Write creator-view.md before Engineer View. Full spec in REFERENCE §4.

1. What's Relevant To Your Work — map to active projects
2. What This Site Understands — 13 value axes as backbone
3. Voice and Editorial POV — editorial stance, implied author
4. Where Your Approach Differs — productive vs fundamental divergence
5. The Challenge — what makes this site hard to use as knowledge
6. The Warning (OPTIONAL) — genuine risks only (ToS, bias, misinfo)
7. Knowledge Candidates — extractable items with type, confidence, effort

Done when: creator-view.md exists AND all MUST sections written AND home-context claims reference actual files in SoNash.

---

Engineer View (Phase 3 of 6 — SHOULD for Standard/Deep)

Six dimensions, 4-band scoring: Performance | Security Headers | Accessibility | SEO | Technical Stack | Mobile Readiness. See REFERENCE §5.

Done when: summary.md contains all 6 bands AND findings.jsonl populated.

---

Value Map (Phase 4 of 6)

Knowledge candidates ranked. Content candidates promoted from content-eval.jsonl high relevance items. Anti-pattern candidates from Creator View §5 "The Challenge". High-link-density trigger (SHOULD): when >40 unique external links, suggest Expedition or cross-site synthesis.

Done when: value-map.json exists AND promotion rules applied.

---

Tag Suggestion (MUST for Standard/Deep)

Follow the canonical protocol in .claude/skills/_shared/TAG_SUGGESTION.md. Per CONVENTIONS §14: at least 3 semantic tags per entry, 8 categories, no upper bound.

Signal sources for website-analysis: creator-view.md, entry notes, engineer-view.md, meta.json, outbound-link ecosystem.

Done when: user-approved tags written to analysis.json.tags AND each extraction-journal.jsonl row.

---

Delegation & Defaults

Gate	Default
--depth unspecified	standard
Quick → Standard gate unanswered	proceed to Standard
Site scope-explosion (>50 pages)	limit to first 50
Coverage Audit unanswered	skip all (logged in audit file)
Tag Suggestion unanswered	never auto-approve — block
Routing menu unanswered	6. Done (cleanup + invocation track)
Prior Feedback Replay (CONV §18)	continue unchanged (logged as shown)

Tag Suggestion auto-approve is forbidden (CONVENTIONS §14.6).

---

Guard Rails (top 5)

1. Compliance first — HARD_BLOCK stops extraction; no data collection.
2. Rate limit safety — respect Retry-After; back off on 429/503.
3. Scope guards — Site >50 pages → soft prompt; no silent auto-expand.
4. superpowers-chrome fallback — if primary fails, fall back gracefully with a WARN; never silently lose extraction fidelity.
5. Write-rejection bypass — hook-rejected prose writes → retry via Bash/Python, never silently skip.

Full guard catalog — REFERENCE §7 (compliance), §15 (tool fallback).

---

Self-Audit (MUST — penultimate phase)

Before presenting results, verify all 9 dimensions:

1. Completeness — all requested artifacts exist on disk
2. Orphan detection — no references to files that weren't written
3. Schema integrity — all JSON artifacts have schema_version
4. Gap analysis — Creator View sections reference actual content
5. Functional verification — state file updated to current phase
6. Multi-agent — dispatch code-reviewer on creator-view.md
7. Regression — if prior analysis exists, compare count deltas
8. Contract — analysis.json matches REFERENCE §1 schema
9. Partial recovery — detect stale artifacts from interrupted runs
10. Prior feedback replay — prior_feedback_shown: true if prior state existed (CONVENTIONS §18)

---

Routing Menu

After Standard/Deep, present:

1. Extract knowledge — pick from value-map, write to extraction-journal.jsonl, regenerate EXTRACTIONS.md
2. Start Expedition — launch Expedition from analyzed page
3. Deep-plan this — inject analysis + creator-view as research context
4. Save to memory — persist key findings
5. Explore insights — deeper Creator View conversation
6. Done — list output files, remove state file, run retro
7. Cross-site synthesis — if 3+ sites analyzed, suggest /synthesize

See REFERENCE §12.

---

State File & Resume

Location: .claude/state/website-analysis.<site-slug>.state.json. Update after every phase. State file stores process_feedback (nullable) from retro. Artifacts as checkpoints: analysis.json, creator-view.md, meta.json persist independently.

---

Retro & Prior Feedback Replay

Retro (CONVENTIONS §10): Before the routing menu, ask: "What worked well? What would you change next time?" Save to process_feedback in the state file. Optional structured dimensions: worked_well, would_change, longest_phase, signal_quality.

Prior Feedback Replay (CONVENTIONS §18): On re-invocation for the same URL, replay prior process_feedback during VALIDATE and ask whether to adjust approach. Log prior_feedback_shown: true.

Invocation tracking — at Done routing:

cd scripts/reviews && npx tsx write-invocation.ts --data '{
  "skill":"website-analysis","type":"skill","success":true,
  "schema_version":1,"completeness":"stub",
  "origin":{"type":"manual"},
  "context":{"target":"SITE_SLUG","mode":"MODE","depth":"DEPTH",
             "score":SCORE,"decisions":DECISION_COUNT,
             "candidates":CANDIDATE_COUNT}
}'

---

Integration

• Siblings: /repo-analysis, /document-analysis, /media-analysis
• Router: /analyze (auto-detects website sources)
• Companion: /synthesize (cross-site, requires 3+ sites)
• Consumers: JASON-OS Domain 02a, /deep-plan (as research context)
• Cross-skill contract: MUST preserve last_synthesized_at field on analysis.json when writing — this field is set by /synthesize Phase 5 and must not be dropped by handler re-runs (v2.0 contract, Session #284).
• Shared artifacts: .research/extraction-journal.jsonl, .research/EXTRACTIONS.md, .research/reading-chain.jsonl

---

Version History

Version	Date	Description
2.0	2026-04-15	Skill-audit batch 2026-04-15-analysis-quartet Wave 2: /analyze router ack, Warm-up, Routing Guide, Delegation & Defaults, consolidated Guard Rails top-5, site-mode scope-explosion soft prompt (>50 pages), Done-when gates, PHASE N of M, Tag Suggestion → _shared ref, Prior Feedback Replay per CONVENTIONS §18, structured retro dimensions, enriched invocation tracking (mode/depth/score/decisions/candidates), output list reformatted as table, mode section condensed to table + REFERENCE pointers, compliance pre-flight condensed to 8 steps + pointer to §7
1.2	2026-04-09	CONVENTIONS alignment: SITE-ANALYSIS.md→creator-view.md, add summary.md, remove links.json from output list (Session #270 E2E test)
1.1	2026-04-06	Convergence: CONVENTIONS.md ref, --depth= flags, retro persistence
1.0	2026-04-06	Initial implementation