---
name: "03 build-breaking planning+research rules"
description: "Universal parallelism + research gates: every build's task graph MUST be parallelized via fan-out architecture (research+brand+media+content concurrent), parallel research agents by era/topic, critical path optimization with concurrency floor, assumption-driven slicing with confidence-tracked decisions. Migrated from prompt-improvements brainstorm 2026-05-10."
metadata:
  version: "1.0.0"
  updated: "2026-05-10"
  effort: "high"
  context: "fork"
license: "Rutgers"
compatibility:
  claude-code: ">=2.0.0"
  agentskills: ">=1.0.0"
---

# 03 — Build-Breaking Planning + Research Rules

Initialized from prompt-improvements brainstorm 2026-05-10 — 4 parallelism rules (#9-12) that bind planning + research phase.

## Every build (***PARALLELISM #1 — FAN-OUT ARCHITECTURE FROM PROMPT-ZERO — UNIVERSAL — BUILD-BREAKING***)

- Build orchestrator MUST spawn ALL boot-time tasks concurrently at prompt-zero — research, brand extraction, media pre-fetch, content corpus crawl, route discovery, sitemap fetch, source-site Wayback lookup
- Never sequentially

### Pipeline

1. Orchestrator boots
2. In single `Promise.all([...])` block launches:
   - `research_task`
   - `brand_extraction_task`
   - `media_prefetch_task`
   - `corpus_crawl_task`
   - `route_discovery_task`
   - `wayback_task`
   - `competitor_scan_task`
3. All must complete before `content_synthesis_task` fires

### Concurrency floor

- 7 boot tasks

### Validator

- `validate-parallel-boot.mjs` — parse `_build_trace.json`, assert ≥7 tasks have overlapping `started_at` windows within 5s of orchestrator boot AND `content_synthesis_task.started_at >= max(boot_tasks.ended_at)`

## Every build (***PARALLELISM #2 — DEEP-RESEARCH AGENTS PER ERA/TOPIC — UNIVERSAL — BUILD-BREAKING***)

- Any site with >50yr history OR >10 content categories OR >100 source-corpus pages MUST split research into ≥3 parallel deep-research agents
- Never single-agent serial crawl

### Splits

- **Era-based** (institutions) — pre-1900 | 1900-1970 | 1970-present
- **Topic-based** (orgs) — products | team | press | case-studies | careers | engineering-blog

### Per-agent output

- `research/<era|topic>-<slug>.json` matching `njsk-timeline-v1` schema
- Fields: `events[]`, `refs[]`, `uncertainties[]`, `verbatim_quotes[]`
- Then merge → dedupe → typecheck → render

### Validator

- `validate-parallel-research.mjs` — assert `research/` contains ≥3 era/topic-segmented JSON files AND their `started_at` windows overlap within 30s

## Every build (***PARALLELISM #3 — CRITICAL-PATH OPTIMIZATION + CONCURRENCY FLOOR — UNIVERSAL — BUILD-BREAKING***)

- Build planner MUST emit `_critical_path.json` before any build phase fires
- Lists every phase, its dependencies, max-concurrency-at-each-step, projected wall-clock
- Phase ordering MUST optimize critical path (longest dependency chain) — never serialize independent tasks

### Concurrency floor per phase

- **Phase 0 (boot)** — ≥7
- **Phase 1 (synthesis)** — ≥3 (page-by-page parallel)
- **Phase 2 (media fill)** — ≥10 (GPT Image 1.5 batch)
- **Phase 3 (validation)** — ≥5 (parallel validators)
- **Phase 4 (deploy)** — ≥1

### Total wall-clock target

- 5-page site — 10 min
- 20-page site — 15 min
- 100-page site — 25 min

### Validator

- `validate-critical-path.mjs` — assert `_critical_path.json` exists with all phases declared + concurrency floors met in `_build_trace.json` AND total duration ≤ projected wall-clock × 1.5

## Every build (***PARALLELISM #4 — ASSUMPTION-DRIVEN SLICING WITH CONFIDENCE-TRACKED DECISIONS — UNIVERSAL — BUILD-BREAKING***)

- Every build plan MUST decompose into vertical slices where each slice carries explicit assumption + confidence (0-1) + fallback

### Format

```
_slice_plan.json[i] = {
  slice_id,
  task,
  parallel_with: [slice_ids],
  depends_on: [slice_ids],
  assumption: "...",
  confidence: 0.X,
  fallback_if_violated: "..."
}
```

### Confidence rules

- **<0.7** — slice MUST emit fact-check sub-task before main task fires
- **≥0.7 + low-risk** — auto-execute
- Assumptions discovered violated during build → slice rolls back to fallback + logs to `_assumption_violations.json`

### Validator

- `validate-slice-confidence.mjs` — assert `_slice_plan.json` has all 5 fields per slice AND no slice with confidence <0.7 lacks fact-check sub-task AND no assumption violation went unlogged

---
name: "Competitive Analysis"
description: "Before building any product: WebSearch for 3-5 competitors, scrape their homepages and pricing pages via WebFetch/Stagehand, extract features, pricing tiers, design patterns, and copy tone. Summarize in comparison table. Scrape source sites for brand assets during rebuilds. Use Firecrawl (self-hosted) for deep crawling."
version: "2.0.0"
updated: "2026-04-23"
---

# Competitive Analysis

## Before First Line of Code

### Step 1: Identify Competitors

1. WebSearch for `"[product category] + [target audience]"` — example: "soup kitchen management software" or "donation platform nonprofit"
2. WebSearch for `"best [product type] 2026"`
3. WebSearch for `"alternatives to [known competitor]"`
4. Identify 3-5 direct competitors

### Step 2: Scrape Each Competitor

For each competitor, fetch:

1. **Homepage** — extract hero copy, value proposition, design style
2. **Pricing page** — extract tiers, amounts, features per tier
3. **Features page** — extract feature list, categorization
4. **About page** — extract team size, story, trust signals
5. **Footer** — extract social links, legal pages, contact

Use WebFetch for public pages. Use FireCrawl (`firecrawl.megabyte.space`) for deeper crawling.

### Step 3: Visual Analysis

1. Take Playwright screenshots of each competitor at 1280px and 375px
2. Analyze color palette, typography, layout patterns, image style
3. Note what looks premium vs. generic
4. Identify design patterns we should adopt or improve upon

### Step 4: Synthesize into Comparison Table

```markdown
## Competitive Landscape — [Product Category]
| Dimension | Competitor A | Competitor B | Competitor C | **Us (Target)** |
|-----------|-------------|-------------|-------------|-----------------|
| **Pricing** | $29/mo | $49/mo | Free + $99/mo | Free + $50/mo |
| **Free tier** | Yes (limited) | No | Yes (generous) | Yes (generous) |
| **Key feature** | [specific] | [specific] | [specific] | [better version] |
| **Design quality** | Generic | Premium | Dated | Premium (dark, bold) |
| **Mobile** | Good | Poor | Good | Excellent |
| **SEO/content** | Blog | None | Docs | Blog + Docs |
| **Social proof** | Logos | Testimonials | None | Both + stats |
| **Speed (LCP)** | 2.1s | 3.5s | 1.8s | < 1.5s target |
| **Accessibility** | Poor | Medium | Good | WCAG AA (verified) |
| **Easter eggs** | None | None | None | Yes (mandatory) |
```

### Step 5: Extract Winning Patterns

1. Which features do ALL competitors have? (table stakes — we must have them)
2. Which features does only the leader have? (differentiation opportunity)
3. What do ALL competitors do poorly? (our biggest opportunity)
4. What pricing model converts best? (evidence from their approach)
5. What design patterns work? (adopt the best, improve on the rest)

## Content Scraping (for Rebuilds)

### Brand Extraction

1. Screenshot the site at multiple viewpoints
2. Extract via AI vision:
   - Primary colors (hex values)
   - Font families and weights
   - Logo (download if possible)
   - Image style (photography, illustration, abstract)
   - Overall mood (formal, casual, technical, warm)
3. Extract from source:
   - Meta tags (title, description, OG)
   - Structured data (JSON-LD)
   - Sitemap (all pages)
   - Social links
   - Contact information

### Content Extraction

1. Scrape ALL text content (never truncate or summarize)
2. Preserve heading hierarchy
3. Extract all image URLs and alt text
4. Capture testimonials and quotes exactly
5. Note which sections appear on which pages
6. Preserve any numbers, statistics, or data points

### Deep Crawling via FireCrawl

```bash
# Self-hosted at firecrawl.megabyte.space
curl -X POST "https://firecrawl.megabyte.space/v1/crawl" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://competitor.com",
    "maxDepth": 3,
    "limit": 50,
    "scrapeOptions": {
      "formats": ["markdown", "html"],
      "includeTags": ["h1","h2","h3","p","li","a","img"]
    }
  }'
```

## Research-Backed Differentiation (Source: First Round Review, Y Combinator)

### How to Beat Competitors

1. **10x better on one dimension** — don't try to be better at everything
2. **Speed** — if you're fastest, users forgive everything else
3. **Design quality** — most B2B/nonprofit tools look terrible; premium design is a moat
4. **Completeness** — competitors often ship 60%; ship 95%
5. **Price** — generous free tier converts more than any marketing
6. **Accessibility** — most competitors fail WCAG; passing is a selling point
7. **Media quality** — real images, real video, real animation (not stock)

### What to Always Beat Competitors On (Emdash Defaults)

- Visual quality (anti-slop design system, `10-experience-and-design-system`)
- Page speed (Cloudflare edge, <1.5s LCP)
- Accessibility (WCAG AA verified, `07/accessibility-gate`)
- Media richness (generated imagery, not stock, `12-media-orchestration`)
- Completeness (no placeholder content, `06-build-and-slice-loop`)
- Motion quality (meaningful animation, `11-motion-and-interaction-system`)
- Easter eggs (delightful hidden features, `06/easter-eggs`)

## Output: Build Plan Integration

After analysis, feed findings into:

- **02-goal-and-brief** — refine product thesis based on competitive gaps
- **03-planning-and-research** — prioritize features that differentiate
- **09-brand-and-content-system** — adopt winning design patterns, improve on weaknesses
- **10-experience-and-design-system** — match or exceed best competitor's visual quality
- **13/stripe-billing** — position pricing competitively

## Enhancement: AI Website Builder Competitive Landscape (April 2026)

### Key Competitors in the AI Builder Space

| Platform | Model | Strengths | Weaknesses | Price |
|----------|-------|-----------|------------|-------|
| **Bolt.new** | Claude Sonnet/Opus 4.6 | Browser-based full-stack, no local setup | WebContainer overhead, npm compat issues | Free (3-8 prompts/day) |
| **bolt.diy** | Any (19 providers) | Open-source, self-hosted, BYO API keys | Requires CLI knowledge, manual setup | Free (self-hosted) |
| **v0** | Vercel's model | Tight Next.js integration, focused UI gen | Frontend-only, locked to Vercel ecosystem | ~$5/mo free tier |
| **Lovable** | Unknown | Non-technical user focus, polished output | Restrictive free tier, mandatory public projects | $25/mo |
| **Replit** | Various | Educational focus, collaborative | Trial-based free tier, costs add up | Variable |
| **Dyad** | BYO API keys | Unlimited free usage, local dev, open-source | Newer product, requires API key setup | Free |

### Market Split

- **Cloud platforms** (Bolt.new, v0, Lovable) — restrictive free tiers, faster iteration, managed hosting
- **Local/self-hosted** (bolt.diy, Dyad) — unlimited free use, privacy, but setup burden

### How to Beat AI Builders (Emdash Differentiation for projectsites.dev)

1. **Design quality** — AI builders produce generic output; our anti-slop design system is a moat
2. **Completeness** — builders ship 60% products; we ship with SEO, a11y, analytics, legal, email
3. **Domain expertise** — builders are general-purpose; we know the exact stack and optimize for it
4. **Post-build quality** — builders stop at "it runs"; we verify via quality gate (Lighthouse 90+, E2E, visual QA)
5. **Integration depth** — builders leave you with code; we deploy to Cloudflare with DNS, SSL, analytics wired up

---
name: "planning-and-research"
description: "Deep web research, competitor scanning, technology evaluation, and implementation planning. Decomposes work into vertical slices, identifies parallel workstreams, tracks assumptions with confidence levels, and designs the critical path for minimum wall-clock time."
metadata:
  version: "2.1.0"
  updated: "2026-05-03"
  effort: "high"
  model: "opus"
license: "Rutgers"
compatibility:
  claude-code: ">=2.0.0"
  agentskills: ">=1.0.0"
priority: 2
pack: "research"
stage: beta
triggers:
  - "research"
  - "plan"
  - "competitor"
paths:
  - "*"
---

# 03 — Planning and Research

Decompose work into parallel vertical slices using deep web research, competitor scanning, and technology evaluation.

## Deep research protocol

Before any non-trivial implementation:

1. Web search top 50 results for primary keyphrase
2. Read top 10 in depth — extract directives + counter-arguments
3. Cross-ref against existing rule mesh
4. Confidence-track every claim 0-1

Use `web_search_20260209` + `web_fetch_20260209` (free when paired with `code_execution_20260120`).

## Competitor scanning

For every website build, run `rules/competitor-research.md` Phase -1 BEFORE Phase 0:

- Identify top 5-10 audience-comparable sites
- Score each on 100-pt rubric (10 dims × 10pts)
- Set ≥15% beat-floor for Phase 6 loop termination

## Technology evaluation

For every new dep / framework / service consideration:

1. **Already have equivalent?** → use it
2. **Feature truly needed?** → if speculative, defer
3. **License?** → OSS free only (per `rules/brian-preferences.md` priority order)
4. **CF compat?** → adapter pattern per `rules/cloudflare-hostable-supervisor.md`
5. **Bundle/perf impact?** → measure before commit
6. **Lighter existing solution?** → prefer
7. Decide: install now · defer · adapter-only · reject + document why

## Implementation planning

### Decomposition

- Identify atomic units (file × layer)
- Mark dependencies between units
- Distinguish independent vs serial chains

### Vertical slicing

Per `06-build-and-slice-loop`:

- Each slice ships through every layer (UI → API → DB → tests → deploy)
- Homepage FIRST (no exceptions)
- Slice = one feature, not one layer

### Parallelism plan

Per `rules/parallel-subagent-economy.md`:

- ≥5-min wall-clock saving + independent → fan out
- Sweet spot 3-4 specialists, ceiling 6
- Batch beyond 6 in waves
- Sonnet default; Opus for security/architect/visual-qa overrides

### Critical path

- Identify longest dependency chain
- Front-load research that gates implementation
- Parallelize everything off the critical path
- Wall-clock = max(critical_path, max parallel branch)

## Assumption tracking

Every assumption logged in `_assumptions.md` with:

- Claim
- Confidence 0-1
- Evidence sources
- Decision impact if wrong
- Verification trigger

Confidence <0.7 → research more. Per `rules/auto-meta-work.md`.

## Three-Layer Knowledge

Per `~/.claude/CLAUDE.md` § Thinking:

- L1 = proven (existing rules + patterns)
- L2 = trending (blog posts, recent papers)
- L3 = first principles (build from scratch)

Prefer L3. Best outcome of research is NOT finding a solution to copy — it's understanding the problem deeply enough to design a better one.

## Self-Argue (before major decisions)

Generate strongest counterargument. If you can't defeat it, decision is wrong.

## Boil-the-lake

Marginal cost of completeness is near-zero. When complete costs minutes more than shortcut, do complete. Boil lakes, flag oceans.

## Output artifacts

- `_research.json` — raw findings, source URLs, confidence
- `_assumptions.md` — tracked claims
- `PLAN.md` — implementation roadmap w/ parallelism plan + critical path
- `_decisions.md` — architectural decisions w/ rationale + alternatives
- `_brief_summary.txt` — 100-word digest for downstream agents