docs: contributor guide improvements proposal

docs/proposals/contributor-guide-improvements.md

@@ -0,0 +1,242 @@
+# Proposal: Contributor Guide Improvements
+
+> **Author:** Flight (Lead)
+> **Date:** 2025-07-24
+> **Status:** Draft — awaiting team review
+> **Goal:** External contributors can be successful with issues and PRs without requiring repeated guidance from Brady and Tamir.
+
+---
+
+## Executive Summary
+
+Squad has strong internal process documentation (CONTRIBUTING.md, PR_REQUIREMENTS.md, PR template) but significant gaps for **external contributors** — people who discover the project, want to help, and need to find their footing without hand-holding. This proposal identifies 8 gaps and recommends 7 concrete deliverables, prioritized by impact on maintainer time savings.
+
+---
+
+## 1. Current State Audit
+
+### What Exists Today (dev branch)
+
+| File | Status | Quality |
+|------|--------|---------|
+| `CONTRIBUTING.md` | ✅ Exists | **Strong** — 300 lines covering setup, build, test, branch strategy, changesets, code style, common tasks. Well-structured. |
+| `CONTRIBUTORS.md` | ✅ Exists | **Good** — lists AI team, community contributors, Insider Program. Good recognition. |
+| `.github/PULL_REQUEST_TEMPLATE.md` | ✅ Exists | **Strong** — What/Why/How/Testing/Docs/Exports/Breaking/Waivers sections with checkboxes. |
+| `.github/PR_REQUIREMENTS.md` | ✅ Exists | **Excellent** — 240 lines, canonical spec for PR requirements by category (a–f), waivers, exceptions. |
+| `SECURITY.md` | ✅ Exists | **Adequate** — directs to GitHub Private Vulnerability Reporting. Minor typo ("manor" → "manner"). |
+| `.github/copilot-instructions.md` | ✅ Exists | **Strong** — git safety rules, team context, capability self-check for Copilot coding agent. |
+| `README.md` | ✅ Exists | **Good** — quick start, install, usage. Points to CONTRIBUTING.md. |
+| `docs/proposals/` | ✅ Exists | 7 existing proposals. Healthy proposal-first culture. |
+
+### What's Missing
+
+| Gap | Impact | Who Suffers |
+|-----|--------|-------------|
+| **No issue templates** (`.github/ISSUE_TEMPLATE/`) | Contributors file unstructured issues; maintainers spend time asking for reproduction steps, versions, environment | Brady, Tamir, triagers |
+| **No CODE_OF_CONDUCT.md** | Standard OSS expectation missing. Some contributors may hesitate without one. GitHub community profile incomplete | Community trust |
+| **No "good first issue" issues** | Label exists (`good first issue`) but **zero issues** currently tagged. New contributors have no on-ramp | New contributors |
+| **No `.squad/` explainer in contributor docs** | External contributors don't know what `.squad/` is, why it exists, or that they should never modify it in PRs | External contributors who include `.squad/` changes |
+| **Branch strategy buried** | Branch info is in CONTRIBUTING.md §Branch Strategy but easy to miss. PR #633 (external) was opened against wrong base — empty body, zero comments, closed | External contributors |
+| **No contributor FAQ / troubleshooting** | Common stumbling blocks (changeset prompts, fork sync, CI failures) require maintainer intervention | All external contributors |
+| **PR #639 pattern** | External contributor submitted quality work but it targeted a feature being removed (#665). No way for contributors to know what's "safe to work on" | Contributors who pick up work |
+| **`status:contributor-invited` label underused** | 8 issues tagged historically, only 2 currently open. No documented workflow for how contributors claim these | Contributors looking for work |
+
+### Friction Patterns from Community PRs
+
+Only **4 external PRs** in the last 100 (out of 100 total) — very low external contribution rate:
+
+| PR | Contributor | Outcome | Friction |
+|----|------------|---------|----------|
+| #608 | @eric-vanartsdalen | ✅ Merged | Clean — security policy revision |
+| #592 | @joniba | ✅ Merged | Clean — hiring wiring guide, high-quality |
+| #639 | @gaburn | ❌ Closed | Worked on REPL feature being removed (#665). No way to know. Brady redirected kindly but work was wasted. |
+| #633 | @JerrettDavis | ❌ Closed | Empty PR body, no description, opened against `dev` — likely a test PR or confusion about process |
+
+**Key insight:** The successful external PRs (#608, #592) came from contributors who already had context. The failed ones (#639, #633) show the "cold start" problem — new contributors lack the context to pick good work and submit correctly.
+
+---
+
+## 2. Proposed Changes
+
+### P1 — High Impact, Low Effort (do first)
+
+#### 2a. GitHub Issue Templates (`.github/ISSUE_TEMPLATE/`)
+
+**What:** Create 4 structured issue templates:
+- `bug_report.yml` — version, environment, reproduction steps, expected vs actual behavior
+- `feature_request.yml` — problem statement, proposed solution, alternatives considered
+- `documentation.yml` — what's missing or wrong, where, suggested improvement
+- `config.yml` — blank issue escape hatch + links to Discussions for questions
+
+**Who it helps:** Brady and Tamir (fewer clarification round-trips), triagers (structured data), reporters (guided through what to include).
+
+**Effort:** ~2 hours. YAML form-based templates (GitHub native).
+
+**Details:**
+- Use YAML form format (not markdown) for required fields — GitHub enforces completion
+- Bug template: require version (`squad version` output), Node version, OS, reproduction steps
+- Feature template: require problem statement before solution (prevents "just add X" issues)
+- Add `type:bug`, `type:feature`, `type:docs` auto-labels per template
+
+---
+
+#### 2b. "Good First Issue" Curation Sprint
+
+**What:** Audit open issues and tag 5–10 with `good first issue`. Create a documented workflow for maintaining the label.
+
+**Who it helps:** New contributors looking for an on-ramp. Reduces "where do I start?" questions.
+
+**Effort:** ~1 hour to tag + 30 min to document the curation workflow.
+
+**Details:**
+- Candidates: documentation gaps, typo fixes, test additions, small CLI improvements
+- Each `good first issue` should include a "Getting Started" comment with:
+  - Which files to look at
+  - What the acceptance criteria are
+  - Which squad member to tag for questions
+- Document the curation workflow in CONTRIBUTING.md: who tags, when, criteria
+
+---
+
+#### 2c. `.squad/` Directory Explainer Section in CONTRIBUTING.md
+
+**What:** Add a clear section explaining what `.squad/` is, why it exists in the repo, and that **external contributors should never modify `.squad/` files in their PRs**.
+
+**Who it helps:** Every external contributor. Prevents accidental `.squad/` changes in PRs.
+
+**Effort:** ~30 minutes.
+
+**Proposed content:**
+```markdown
+## The .squad/ Directory
+
+The `.squad/` directory contains Squad's AI team state — agent charters, decision history,
+routing rules, and accumulated learnings. It is managed exclusively by the Squad team.
+
+**For external contributors:**
+- ❌ Do NOT modify any files in `.squad/` in your PRs
+- ❌ Do NOT include `.squad/` changes in your commits
+- ✅ You can READ `.squad/decisions.md` to understand team conventions
+- ✅ You can READ agent charters to understand domain ownership
+
+If your PR includes `.squad/` changes, you'll be asked to remove them before review.
+```
+
+---
+
+### P2 — Medium Impact, Medium Effort
+
+#### 2d. CODE_OF_CONDUCT.md
+
+**What:** Adopt the Contributor Covenant (v2.1), the standard for OSS projects. Customized with Squad-specific enforcement contacts.
+
+**Who it helps:** Community trust. GitHub community profile completion. Sets behavioral expectations.
+
+**Effort:** ~30 minutes (adopt standard, customize contact info).
+
+**Details:**
+- Use Contributor Covenant v2.1 (industry standard, used by Node.js, Rails, etc.)
+- Enforcement: Brady as primary contact
+- Link from CONTRIBUTING.md and README.md
+
+---
+
+#### 2e. Contributor FAQ / Troubleshooting Section
+
+**What:** Add a "Common Issues" section to CONTRIBUTING.md covering the questions maintainers answer repeatedly.
+
+**Who it helps:** All external contributors. Direct time savings for Brady and Tamir.
+
+**Effort:** ~1 hour.
+
+**Proposed topics:**
+- "My PR CI is failing" — how to read CI output, common causes (missing changeset, build errors, lint failures)
+- "Which branch do I target?" — always `dev`, never `main`. With a bold callout box.
+- "Do I need a changeset?" — yes, always. How `npx changeset add` works. What to pick for patch/minor/major.
+- "How do I know what's safe to work on?" — look for `good first issue`, `status:contributor-invited`, `help wanted` labels. Avoid issues with `squad:*` labels (team-internal). Check the issue isn't already assigned.
+- "My fork is out of date" — step-by-step rebase instructions (already in CONTRIBUTING.md, but worth a FAQ entry pointing to it)
+- "What's the `.squad/` directory?" — link to the explainer section
+
+---
+
+#### 2f. "Contributing" Section Enhancement in README.md
+
+**What:** Expand the README's contributor section beyond just linking to CONTRIBUTING.md. Add a quick "Ways to Contribute" section.
+
+**Who it helps:** Discovery — README is the first file most people read.
+
+**Effort:** ~30 minutes.
+
+**Proposed content:**
+```markdown
+## Contributing
+
+We welcome contributions! Here's how to get involved:
+
+- 🐛 **Report bugs** — [Open an issue](link) using the bug report template
+- 💡 **Suggest features** — [Open an issue](link) using the feature request template
+- 🔧 **Fix something** — Look for [`good first issue`](link) or [`help wanted`](link) labels
+- 📖 **Improve docs** — Typos, clarity, missing examples — all welcome
+
+**Before you start coding**, read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, branch strategy, and PR requirements.
+
+All PRs target the `dev` branch. See [Branch Strategy](CONTRIBUTING.md#branch-strategy) for details.
+```
+
+---
+
+### P3 — Nice to Have
+
+#### 2g. SECURITY.md Typo Fix
+
+**What:** Fix "manor" → "manner" (line 19). Minor but noticed during audit.
+
+**Who it helps:** Professional appearance.
+
+**Effort:** 30 seconds.
+
+---
+
+## 3. Priority Order
+
+| Priority | Deliverable | Effort | Maintainer Time Saved | Ship With |
+|----------|-------------|--------|----------------------|-----------|
+| **P1** | Issue templates (2a) | 2 hrs | High — structured reports reduce back-and-forth | This PR or immediate follow-up |
+| **P1** | Good first issue curation (2b) | 1.5 hrs | High — gives contributors a clear on-ramp | Separate task (requires issue audit) |
+| **P1** | `.squad/` explainer (2c) | 30 min | Medium — prevents common PR mistake | This PR or immediate follow-up |
+| **P2** | CODE_OF_CONDUCT.md (2d) | 30 min | Low direct, high trust signal | This PR or immediate follow-up |
+| **P2** | Contributor FAQ (2e) | 1 hr | High — answers repeated questions | This PR or immediate follow-up |
+| **P2** | README contributing section (2f) | 30 min | Medium — improves discovery | This PR or immediate follow-up |
+| **P3** | SECURITY.md typo (2g) | 30 sec | None | Any PR |
+
+**Recommended execution:** Items 2a + 2c + 2e + 2f + 2g can be shipped in a single PR (estimated 4 hours total). Item 2b (good first issue curation) is a separate task requiring issue-by-issue audit. Item 2d (CODE_OF_CONDUCT) can ship standalone.
+
+---
+
+## 4. Success Criteria
+
+After these changes ship:
+
+1. **A new contributor can go from "I found this repo" to "my PR is ready for review" using only the docs** — no DMs, no repeated questions to Brady/Tamir.
+2. **Every bug report includes version, OS, and reproduction steps** — enforced by issue template required fields.
+3. **Contributors know what to work on** — `good first issue` and `status:contributor-invited` labels are actively maintained with 5+ open issues at all times.
+4. **No PRs include `.squad/` changes** — explainer section makes the boundary clear.
+5. **Brady and Tamir can respond to contributor questions with links** — "See [FAQ: Which branch do I target?](CONTRIBUTING.md#faq)" instead of writing the answer each time.
+
+---
+
+## 5. What This Does NOT Cover
+
+- **Automated PR checks for `.squad/` changes** — that's a CI gate (separate issue)
+- **Contributor license agreement (CLA)** — Squad uses MIT, no CLA needed currently
+- **Discord/Slack community** — out of scope, GitHub Discussions is the channel
+- **Docs site contributor guide** — the Astro docs site (`docs/`) has its own needs; this proposal focuses on repo-level contributor docs
+
+---
+
+## 6. Open Questions for Team
+
+1. **Who should be the CODE_OF_CONDUCT enforcement contact?** Brady as repo owner is the default, but should we list a backup?
+2. **Should we add a `.github/FUNDING.yml`?** Not strictly contributor guidance but often expected in OSS.
+3. **Should `status:contributor-invited` be renamed to `help wanted`?** GitHub surfaces `help wanted` specially in search and explore. We have both labels — should we consolidate?
+4. **PR #639 pattern prevention:** Should we add a "Do Not Contribute" label or a "being removed" label for features that are being deprecated? This would prevent contributors from wasting effort on doomed features.