scout

name	scout
description	Analyze external URLs to evaluate fit with your project and auto-create GitHub issues with structured verdicts. Uses a lightweight project fingerprint for token-efficient codebase analysis with git-hash-based cache refresh.

Scout

Analyze external URLs (tech blogs, tools, libraries, methodologies) to evaluate fit with the current project and auto-create a GitHub issue with a structured verdict.

Installation

npx skills add baekenough/baekenough-skills --skill scout

Commands

Command	Description
/scout <url>	Analyze URL and create issue with verdict
/scout init	Force regenerate project fingerprint

Verdict Taxonomy

Verdict	Meaning	Labels	Follow-up
INTERNALIZE	Aligns with project; should become part of codebase	scout:internalize + P1/P2/P3	Direct implementation or deep research
INTEGRATE	Useful but best kept as external dependency	scout:integrate + P2/P3	Integration review
SKIP	Irrelevant or duplicates existing functionality	scout:skip	Issue created then auto-closed

Pre-flight Guards

Run both guards before any analysis.

Guard 1: URL Validity (GATE)

Validate URL syntax. If the URL does not match ^https?://, abort immediately with an error message. Do not proceed.

Guard 2: Duplicate Scout (WARN)

Search existing issues for prior scout reports on the same URL domain:

DOMAIN=$(echo "$URL" | sed 's|https\?://||' | cut -d'/' -f1)
gh issue list --state all --label "scout:internalize,scout:integrate,scout:skip" \
  --json number,title,body --jq ".[] | select(.body | contains(\"$DOMAIN\"))"

If a matching issue is found, warn the user and ask whether to proceed. Do not auto-abort — the user may want a re-evaluation.

Display Format

Before executing, show the plan and ask for confirmation:

[Scout] {url}
├── Phase 0: Project Fingerprint (cached/refreshed)
├── Phase 1: Fetch & Summarize
├── Phase 2: Load Project Context
├── Phase 3: Fit Analysis
└── Phase 4: Issue Creation

Execute? [Y/n]

Only proceed after the user confirms (or presses Enter for the default Y).

---

Project Fingerprint

Purpose

Instead of reading the full codebase each time (50K+ tokens for large projects), scout maintains a lightweight fingerprint file that captures the project's essence in ~3KB (~1K tokens). The fingerprint is re-used across runs and only refreshed when the codebase actually changes.

Location

.scout/fingerprint.json — should be gitignored. Add .scout/ to .gitignore if not already present.

JSON Schema

{
  "git_hash": "abc1234",
  "generated_at": "2026-04-02T10:00:00Z",
  "project": {
    "name": "my-project",
    "description": "extracted from README first line"
  },
  "tech_stack": {
    "primary_languages": ["TypeScript", "Python"],
    "language_distribution": {"TypeScript": 65, "Python": 30, "Shell": 5},
    "frameworks": ["Next.js", "FastAPI"],
    "package_managers": ["npm", "pip"]
  },
  "dependencies": {
    "key_deps": ["react", "next", "fastapi", "sqlalchemy"],
    "dev_deps_count": 45,
    "prod_deps_count": 23
  },
  "structure": {
    "total_files": 342,
    "total_dirs": 48,
    "top_level_dirs": ["src", "tests", "docs", "scripts"],
    "test_framework": "jest",
    "ci_system": "github-actions"
  },
  "skills_and_agents": {
    "has_claude_md": true,
    "skills_count": 5,
    "skills_list": ["dev-review", "commit", "deploy"],
    "agents_count": 3,
    "agents_list": ["backend-expert", "frontend-expert"]
  },
  "philosophy_summary": "2-3 sentence summary of the project's guiding principles, extracted from CLAUDE.md"
}

Generation Steps

Generate using zero-token Bash/Glob/Grep calls for all structured data. Only the philosophy_summary field requires LLM processing.

Step 1 — Git hash:

git rev-parse HEAD

Step 2 — Language distribution:

find . -type f -not -path './.git/*' | head -1000 \
  | awk -F. 'NF>1{print $NF}' | sort | uniq -c | sort -rn | head -20

Step 3 — Dependencies: Read the following files if they exist (use Glob then Read):

• package.json → extract dependencies and devDependencies
• requirements.txt → list top 10 packages
• go.mod → extract require block
• Cargo.toml → extract [dependencies]
• pyproject.toml → extract [tool.poetry.dependencies]

Step 4 — Top-level directories:

find . -maxdepth 1 -type d | grep -v '^\.$' | sed 's|^\./||' | sort

Step 5 — Skills inventory:

ls .claude/skills/*/SKILL.md 2>/dev/null | sed 's|.claude/skills/||' | sed 's|/SKILL.md||'

Step 6 — Agents inventory:

ls .claude/agents/*.md 2>/dev/null | sed 's|.claude/agents/||' | sed 's|\.md||'

Step 7 — Philosophy summary (LLM): Read the first 50 lines of CLAUDE.md if it exists. Summarize the project's guiding principles and philosophy in 2-3 sentences. This is the only step that consumes LLM tokens (~500 tokens).

Step 8 — Project name/description:

head -10 README.md 2>/dev/null

Extract the project name from the first # heading and description from the first non-heading paragraph.

Total LLM cost for full generation: ~3K tokens (dominated by philosophy summary).

Refresh Strategy

LAST_HASH=$(jq -r '.git_hash' .scout/fingerprint.json 2>/dev/null)
CURRENT_HASH=$(git rev-parse HEAD)

Condition	Action	Token Cost
Same hash	Use cached fingerprint as-is	0
Different hash, < 20 changed files	Patch fingerprint (update changed sections only)	~500
Different hash, >= 20 changed files	Full regeneration	~3K
No fingerprint file	Full generation	~3K

Delta Patch Logic

When the hash differs and fewer than 20 files changed, identify what changed:

git diff --name-only $LAST_HASH $CURRENT_HASH

Use this list to determine which sections to regenerate:

Changed Files	Section to Regenerate
package.json, requirements.txt, go.mod, Cargo.toml	dependencies
Files added or removed (structure)	structure.total_files, structure.total_dirs
CLAUDE.md	philosophy_summary
Any other source files	tech_stack.language_distribution only

All other sections remain unchanged from the cached fingerprint.

---

Workflow Phases

Phase 0: Ensure Fingerprint

1. Check if .scout/fingerprint.json exists.
2. If not → run full generation (all 8 steps above). Write the result to .scout/fingerprint.json.
3. If exists → compare git hashes using the Refresh Strategy table above. Apply delta patch or full regen as needed.
4. Load the fingerprint into context (~1K tokens).

For /scout init, skip the hash check and always run full regeneration.

Phase 1: Fetch & Summarize

1. WebFetch(url) — retrieve page content.
2. Extract from the fetched content:
   • Title: the page/article title
   • Purpose: what it does or proposes in 1-2 sentences
   • Key technology: languages, frameworks, tools mentioned
   • Approach: methodology or key technique
3. If the fetch fails (HTTP error, timeout, or empty response) → abort with an error message. Do not proceed to Phase 2.

Phase 2: Load Project Context

1. The fingerprint from Phase 0 is already loaded in context.
2. Additionally, read the first 100 lines of CLAUDE.md if it exists — this provides richer project philosophy for Phase 3.
3. Total context budget for project information: ~3K tokens.

Phase 3: Fit Analysis

Analyze the external content (Phase 1 output) against the project context (Phase 2 output) across four dimensions:

Dimension	Question
Project alignment	Does it match the project's stated philosophy and goals?
Technical fit	Does it complement or overlap with the existing tech stack and dependencies?
Integration effort	How much work to adopt? (XS = hours, S = days, M = weeks, L = months)
Value proposition	What concrete benefit does it bring to this project?

Analysis prompt template:

You are evaluating whether to adopt an external resource for a software project.

## External Resource (from Phase 1)
{phase1_summary}

## Project Fingerprint
{fingerprint}

## Project Context (CLAUDE.md excerpt)
{claude_md_context}

Analyze the four dimensions:
1. Project alignment — does the resource match the project's goals and philosophy?
2. Technical fit — does it complement or conflict with the existing tech stack?
3. Integration effort — estimate XS/S/M/L with brief justification.
4. Value proposition — what concrete benefit does it bring?

Based on this analysis, produce:
- **verdict**: INTERNALIZE | INTEGRATE | SKIP
- **priority**: P1 | P2 | P3 (omit for SKIP)
- **rationale**: 2-3 sentences explaining the verdict
- **alignment_table**: rows for Philosophy, Technical Fit, Overlap, Effort (✓/✗ + explanation)
- **recommendation**: specific adoption plan or clear skip reason
- **next_steps**: 2-3 concrete action items (omit for SKIP)

Phase 4: Issue Creation

Step 1: Ensure labels exist (idempotent)

gh label create "scout:internalize" --color "0E8A16" --description "Scout: should be internalized" 2>/dev/null || true
gh label create "scout:integrate" --color "1D76DB" --description "Scout: keep as external dependency" 2>/dev/null || true
gh label create "scout:skip" --color "D4C5F9" --description "Scout: skip" 2>/dev/null || true

Run these before creating the issue. The || true ensures the command succeeds even if the label already exists.

Step 2: Create issue

gh issue create \
  --title "[scout:{verdict}] {title}" \
  --label "scout:{verdict},P{n}" \
  --body "{body}"

• gh auto-detects the repository from the current working directory via the git remote. No repo configuration required.
• For SKIP verdict, omit the priority label: --label "scout:skip".

Step 3: Auto-close for SKIP

If the verdict is SKIP, immediately close the issue after creation:

gh issue close {issue_number} --comment "Auto-closed: verdict is SKIP."

---

Issue Body Template

## Scout Report: {title}

**Source**: {url}
**Verdict**: {INTERNALIZE | INTEGRATE | SKIP}
**Priority**: {P1 | P2 | P3}

## Summary
{2-3 sentence summary of what the external resource is and does}

## Project Alignment
| Criterion | Fit | Rationale |
|-----------|-----|-----------|
| Philosophy alignment | ✓/✗ | {explanation} |
| Technical fit | ✓/✗ | {explanation} |
| Existing overlap | ✓/✗ | {overlapping tools or dependencies} |
| Integration effort | XS/S/M/L | {explanation} |

## Recommendation
{Specific adoption plan, or clear reason for skipping}

## Next Steps
- [ ] {action 1}
- [ ] {action 2}

---
Generated by `/scout`

For SKIP verdict, the "Next Steps" section may be omitted.

---

Escalation

When the verdict is INTERNALIZE and the integration effort is M or L, display this advisory after the result:

[Advisory] This integration is non-trivial (effort: {M|L}).
Consider running a deep analysis or creating a sub-task breakdown before proceeding.

This is advisory only — do not block issue creation.

---

Result Display

After all phases complete, display:

[Scout Complete] {title}
├── Verdict: {INTERNALIZE | INTEGRATE | SKIP}
├── Priority: {P1 | P2 | P3}
├── Issue: #{number}
└── Fingerprint: {cached (hash {short_hash}) | refreshed | generated}

---

Validation Rules

Rule	Check	On Failure
URL format	Must match ^https?://	Abort (GATE)
gh CLI availability	gh --version exits 0	Abort with install instructions
git repository	git rev-parse HEAD exits 0	Warn; fingerprint generation skipped, use partial context
Fingerprint freshness	Hash comparison (see Refresh Strategy)	Auto-refresh before proceeding
WebFetch result	Non-empty response with readable content	Abort if fetch fails