Spell Bpap

## Summary

**Research a topic and produce a structured best-practices and antipatterns document.** Combines web research, codebase analysis, and structured output into a practical guide with numbered best practices (BP) and named antipatterns (AP).

**Arguments:** `$ARGUMENTS` (required) - Topic for best-practices and antipatterns research. Optional flag: `--no-save` (output to conversation only, don't write file)

**Output:** Structured best-practices and antipatterns document output to the conversation and saved to `docs/bpap-<topic-slug>.md` by default. Use `--no-save` to output to conversation only.

---

## Process

### Phase 1: Extract

**Step 1: Parse Arguments**

**If `$ARGUMENTS` is empty:**
Ask the user: "What topic should I research best practices and antipatterns for?"

**Otherwise:**
- Extract the topic from `$ARGUMENTS`
- Parse optional flag: `--no-save` — output to conversation only, don't write file
- Generate a slug from the topic: lowercase, spaces and special characters replaced with hyphens (e.g., "Git commit messages" -> "git-commit-messages")
- Determine scope: **narrow** (1-3 concerns) or **broad** (3+ distinct subtopics)

**Step 2: Research**

Gather best practices and antipatterns from multiple sources:

**Web research (if available):**
Search the web for current best practices, antipatterns, common mistakes, and style guides for the topic.

**Codebase analysis (if relevant):**
- Search for existing usage patterns of the topic in the current codebase
- Note what the codebase already does well vs. where it deviates from best practices

**Scan for existing bpap files:**
- Search `docs/` for `bpap-*.md` or `*bpap*.md` files — note related topics for the Cross-References section

**Scan for existing idiomatic files:**
- Search for any idiomatic constraint files related to the topic for cross-referencing

**Graceful degradation:** If web search is unavailable, rely on built-in knowledge and codebase analysis. Note at the top that results are based on training knowledge, not live research.

### Phase 2: Compose

**Step 3: Choose Structure**

Pick one of two structures based on scope:

- **Flat** (narrow topic, 1-3 concerns): Single `## Best Practices` section followed by `## Antipatterns`. Items numbered `BP-1`, `BP-2`... and `AP-1`, `AP-2`...
- **Sectioned** (broad topic, 3+ subtopics): Multiple `## N. Section Title` headings, each with `### Best Practices` and `### Antipatterns` subsections. Items numbered `BP-N.1`, `BP-N.2`... and `AP-N.1`, `AP-N.2`...

**Decision rule:** If the topic has 3+ distinct subtopics that each warrant their own best practices, use sectioned. Otherwise use flat.

**Step 4: Compose the Document**

Apply the output format below. For each item:
- **Best Practice:** Imperative title + what to do and why + rationale with evidence or source
- **Antipattern:** Named pattern + what it looks like + why it's tempting + consequences + what to do instead

**Decision rule for antipatterns vs. best practices:** An antipattern has a name, a temptation, and consequences. If you can't fill all three fields, fold it into a best practice as a "don't" with rationale.

### Phase 3: Verify

**Step 5: Self-Check**

Before presenting the document, verify against this quality rubric:

- [ ] Every BP has a rationale with evidence or source
- [ ] Every AP has a name + trap analysis ("why it's tempting")
- [ ] BPs and APs don't duplicate each other
- [ ] Cross-refs use BP-X.Y/AP-X.Y IDs when referencing other bpap docs
- [ ] "When to Break These Rules" has 2-3 specific items (not blanket disclaimers)
- [ ] Sources section exists (even if "Based on training knowledge")
- [ ] Advice is specific, not truistic ("use `const`" not "use appropriate declarations")
- [ ] Freshness metadata present (date, source, review-after)
- [ ] AI Rules Distillation appendix included
- [ ] Idiomatic cross-references added (if files exist)

Fix any issues before presenting the output.

**Step 6: Save**

**Default behavior (no `--no-save` flag):**
- Use the slug generated in Step 1
- Write the document to `docs/bpap-<topic-slug>.md`
- If the file already exists: warn the user, note what changed, and overwrite (recoverable via git)
- Confirm: "Saved to `docs/bpap-<topic-slug>.md`"

**If `--no-save` flag present:**
- Output to conversation only
- Note: "Not saved. Run again without `--no-save` to persist for cross-referencing."

---

## Output Format

Use standard markdown only. Do not use Unicode box-drawing characters. Do not add explanatory text outside the structured sections. Only use headers and sections specified in this format.

### Flat structure (narrow topics)