feat(skills): add ralph-two-pass-scan skill -- two-pass lightweight scan before selective hydration

[tamirdresher]

Summary

Adds the
alph-two-pass-scan\ skill to .squad/skills/, implementing the two-pass issue scanning pattern proposed in #596.

What This Adds

*.squad/skills/ralph-two-pass-scan/SKILL.md* — documents the pattern for cutting GitHub API calls by ~72% per Ralph round:

• Pass 1 — Lightweight scan: \gh issue list --json number,title,labels,assignees\ (no body)
• Pass 2 — Selective hydration: Only issues surviving the filter get full \gh issue view\ treatment

Filter Rules (Pass 1 → skip hydration if)

Condition	Reason
\�ssignees\ non-empty AND no \status:needs-review\	Already owned
Labels contain \status:blocked\ or \status:waiting-external\	Externally gated
Labels contain \status:done\ or \status:postponed\	Closed loop
Title matches stale/noisy pattern	Low-signal

Rule of thumb: hydrate ≤ 30% of scanned list. If more than 30% survive Pass 1, tighten filter rules.

Why

Ralph's default N+1 scan pattern pulls full JSON for every open issue. For repos with 50-200 open issues, this burns context budget on issues that don't need action. The two-pass pattern cuts API calls from N+1 to ~7 per round.

Fixes #596

[bradygaster]

Flight's Review — ralph-two-pass-scan skill

Hey Tamir — great concept here. The two-pass scan pattern is exactly the kind of optimization Ralph needs, and the 72% API call reduction math checks out. Content quality is solid. A few things to tighten up before we merge:

1. SKILL.md format — needs YAML frontmatter ❌

All skills in .squad/skills/ use the template from .squad/skill.md (see economy-mode or gh-auth-isolation for examples). Your SKILL.md uses inline bold text for metadata instead of the required YAML frontmatter.

Expected format:

---
name: "ralph-two-pass-scan"
description: "Two-pass lightweight scan before selective hydration, cutting Ralph GitHub API calls ~72%"
domain: "work-monitoring"
confidence: "high"
source: "manual"
---

2. Missing template sections ❌

The skill template requires Examples and Anti-Patterns sections. Suggestions:

• Examples: Show a before/after with a 50-issue repo — how many API calls in the old N+1 pattern vs the two-pass approach
• Anti-Patterns: e.g., "Don't skip hydration for issues with status:needs-review even if assigned" or "Don't cache Pass 1 results across rounds — issue state changes between scans"

3. Changeset frontmatter is empty ⚠️

.changeset/ralph-two-pass-scan-skill.md has ---\n--- with no package bump. Since this is a docs-only skill addition, it likely doesn't need a version bump, but the changeset format should either declare that explicitly or be omitted. Check how other docs-only PRs handle this (e.g., keda-scaler-docs.md uses "@bradygaster/squad-cli": patch).

Summary

Aspect	Status
Targets dev	✅
Content quality	✅ Solid
Duplication check	✅ No overlap
Security	✅ Clean
Skill template format	❌ Needs YAML frontmatter
Required sections	❌ Missing Examples + Anti-Patterns
Changeset	⚠️ Empty frontmatter

Fix the format issues and this is a quick approve. Nice work on the optimization analysis 👍

[Copilot]

Pull request overview

Adds a new team skill under .squad/skills/ documenting Ralph’s proposed two-pass GitHub issue scanning approach (lightweight list pass followed by selective hydration), with a corresponding changeset entry to track the addition.

Changes:

• Add ralph-two-pass-scan skill documentation describing pass-1 filtering rules and pass-2 hydration command usage.
• Add a changeset entry announcing the new skill.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
.squad/skills/ralph-two-pass-scan/SKILL.md	New skill doc describing two-pass scan + selective hydration rules/commands.
.changeset/ralph-two-pass-scan-skill.md	Changeset note documenting the addition of the new skill.

[Copilot]

This SKILL.md lacks the YAML frontmatter used by the skill tooling (e.g., consult extraction classifies skills by frontmatter containing at least name: and confidence:). Without it, this file may be treated as a generic decision/markdown doc and lose its skill metadata (name/domain) in listings/extraction. Add --- frontmatter with name, description, domain, confidence (and optionally source/tools/triggers/roles) and move/remove the current bold metadata lines to avoid duplication.

Suggested change

	# Skill: Ralph — Two-Pass Issue Scanning
	**Confidence:** high
	**Domain:** work-monitoring
	**Last validated:** 2026-03-24
	---
	name: Ralph — Two-Pass Issue Scanning
	description: Two-pass GitHub issue scanning to reduce GitHub API calls via selective hydration.
	domain: work-monitoring
	confidence: high
	last_validated: 2026-03-24
	---
	# Skill: Ralph — Two-Pass Issue Scanning

[Copilot]

The call-count claim here (“N+1 to ~7 per round”, “~72% reduction”) doesn’t follow from the documented algorithm below. Two-pass scanning changes calls from (1 + N hydrations) to (1 + M hydrations), where M is the number of issues that survive Pass 1 (e.g., with a 30% hydration target and limit 100, that’s up to 31 calls, not ~7). Consider rewriting this to an equation/assumption-based statement so it stays accurate across repos.

Suggested change

	Cuts GitHub API calls from N+1 to ~7 per round (~72% reduction) by separating list scanning from full hydration.
	Reduces GitHub API calls by moving from full hydration (1 + N calls for N listed issues) to selective hydration (1 + M calls, where M is the number of issues that survive Pass 1 and typically M ≪ N; for example, with N = 100 and a 30% hydration target, this is at most 31 calls vs 101, ~69% reduction) by separating list scanning from full hydration.

[Copilot]

These command snippets omit the language tag on the fenced code block. Other skills typically use tagged fences (e.g., bash / sql) for readability and consistent rendering in docs tooling; consider tagging this block as bash.

[Copilot]

Same as above: tag this fenced block with a language (bash) to match the rest of the skill docs and improve readability.