Stack Overflow Discovery Adapter (Phase 1)

[bradygaster]

Overview

Implement Stack Exchange API v2.3 adapter to discover Aspire-tagged questions on Stack Overflow. Provides direct signal for documentation gaps (unanswered questions), adoption friction, and community pain patterns.

Background

Per gap analysis:

• Current blind spot: Real pain/confusion signals at 15% completeness
• Stack Overflow value: 20-60 questions/week, API requires no auth (optional API key for higher rate limits)
• Documentation intelligence: Unanswered questions = missing docs or confusing features
• Signal types: "How do I...?", error messages, configuration issues

Requirements

• Implement StackOverflowSourceAdapter extending SourceAdapter interface
• Use Stack Exchange API v2.3: \https://api.stackexchange.com/2.3/questions?tagged={tag}&site=stackoverflow\
• Search tags: "aspire", "dotnet-aspire"
• Extract: title, author, question URL, score, answer count, view count, creation date, tags, body excerpt
• Map to ContentItem type with channel="stackoverflow", source="stackoverflow"
• Optional: Support \STACKOVERFLOW_API_KEY\ env var for higher rate limits (10,000/day vs 300/day)
• Add metadata field: { isAnswered: boolean, answerCount: number, viewCount: number, score: number }\
• Respect rate limits: 30 requests/second (or per API key quota)
• Handle API quota exhaustion gracefully (log warning, return partial results)

Squad SDK Integration

• Adapter registration: Auto-discovered by SourceRegistry
• Validation logic: StackOverflowSourceAdapter.validate() checks for optional STACKOVERFLOW_API_KEY env var (warns if missing, proceeds anyway)
• Metadata enrichment: Adds Stack Overflow-specific metrics (answer count, views, score) for signal analysis

Acceptance Criteria

• AC1: Adapter discovers 10+ Aspire-related questions per run
• AC2: Each question maps to ContentItem with: id, title, url, author, publishedAt, tags, answerCount, viewCount, score
• AC3: Unanswered questions flagged via \isAnswered: false\ in metadata (enables "documentation gap" report)
• AC4: If API quota exhausted (HTTP 400 with backoff field), adapter logs warning and stops querying
• AC5: If STACKOVERFLOW_API_KEY is set, adapter uses authenticated endpoint (higher quota)
• AC6: Stack Overflow questions appear in reports with channel="stackoverflow"

Dependencies

Depends on: Issue #1 (Architecture Refactor)

Assigned To

• Bunk (Community scout, implementation)

Estimated Effort

1 session

• Implement StackOverflowSourceAdapter
• Test with/without API key
• Validate unanswered question detection

[github-actions]

🏗️ Squad Triage — Freamon (Lead / Editor-in-Chief)

Issue: #7 — Stack Overflow Discovery Adapter (Phase 1)
Assigned to: Freamon (Lead / Editor-in-Chief)
Reason: No specific domain match — assigned to Lead for further analysis

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

• Freamon (Lead / Editor-in-Chief) → label: squad:freamon
• McNulty (TypeScript Implementer) → label: squad:mcnulty
• Kima (Source Scout (Content)) → label: squad:kima
• Bunk (Source Scout (Community)) → label: squad:bunk
• Omar (Signal Analyst) → label: squad:omar
• Bubbles (Taxonomy + Dedupe Librarian) → label: squad:bubbles
• Daniels (Copilot SDK Specialist) → label: squad:daniels
• Stringer (Squad SDK Orchestrator) → label: squad:stringer
• Ralph (Work Monitor) → label: squad:ralph
• @copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

[github-actions]

🔄 Ralph — Auto-Triage

Assigned to: Freamon (Lead / Editor-in-Chief)
Reason: No domain match — routed to Lead

Ralph auto-triaged this issue via the squad heartbeat. To reassign, swap the squad:* label.

[github-actions]

🔄 Ralph — Auto-Triage

Assigned to: Freamon (Lead / Editor-in-Chief)
Reason: No domain match — routed to Lead

Ralph auto-triaged this issue via the squad heartbeat. To reassign, swap the squad:* label.

[github-actions]

🔄 Ralph — Auto-Triage

Assigned to: Freamon (Lead / Editor-in-Chief)
Reason: No domain match — routed to Lead

Ralph auto-triaged this issue via the squad heartbeat. To reassign, swap the squad:* label.