| 1 | # Out-of-Scope Knowledge Base |
| 2 | |
| 3 | The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes: |
| 4 | |
| 5 | 1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed |
| 6 | 2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it |
| 7 | |
| 8 | ## Directory structure |
| 9 | |
| 10 | ``` |
| 11 | .out-of-scope/ |
| 12 | ├── dark-mode.md |
| 13 | ├── plugin-system.md |
| 14 | └── graphql-api.md |
| 15 | ``` |
| 16 | |
| 17 | One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file. |
| 18 | |
| 19 | ## File format |
| 20 | |
| 21 | The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time. |
| 22 | |
| 23 | ```markdown |
| 24 | # Dark Mode |
| 25 | |
| 26 | This project does not support dark mode or user-facing theming. |
| 27 | |
| 28 | ## Why this is out of scope |
| 29 | |
| 30 | The rendering pipeline assumes a single color palette defined in |
| 31 | `ThemeConfig`. Supporting multiple themes would require: |
| 32 | |
| 33 | - A theme context provider wrapping the entire component tree |
| 34 | - Per-component theme-aware style resolution |
| 35 | - A persistence layer for user theme preferences |
| 36 | |
| 37 | This is a significant architectural change that doesn't align with the |
| 38 | project's focus on content authoring. Theming is a concern for downstream |
| 39 | consumers who embed or redistribute the output. |
| 40 | |
| 41 | ```ts |
| 42 | // The current ThemeConfig interface is not designed for runtime switching: |
| 43 | interface ThemeConfig { |
| 44 | colors: ColorPalette; // single palette, resolved at build time |
| 45 | fonts: FontStack; |
| 46 | } |
| 47 | ``` |
| 48 | |
| 49 | ## Prior requests |
| 50 | |
| 51 | - #42 — "Add dark mode support" |
| 52 | - #87 — "Night theme for accessibility" |
| 53 | - #134 — "Dark theme option" |
| 54 | ``` |
| 55 | |
| 56 | ### Naming the file |
| 57 | |
| 58 | Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file. |
| 59 | |
| 60 | ### Writing the reason |
| 61 | |
| 62 | The reason should be substantive — not "we don't want this" but why. Good reasons reference: |
| 63 | |
| 64 | - Project scope or philosophy ("This project focuses on X; theming is a downstream concern") |
| 65 | - Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture") |
| 66 | - Strategic decisions ("We chose to use A instead of B because...") |
| 67 | |
| 68 | The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals. |
| 69 | |
| 70 | ## When to check `.out-of-scope/` |
| 71 | |
| 72 | During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue: |
| 73 | |
| 74 | - Check if the request matches an existing out-of-scope concept |
| 75 | - Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md` |
| 76 | - If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?" |
| 77 | |
| 78 | The maintainer may: |
| 79 | |
| 80 | - **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed |
| 81 | - **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage |
| 82 | - **Disagree** — the issues are related but distinct, proceed with normal triage |
| 83 | |
| 84 | ## When to write to `.out-of-scope/` |
| 85 | |
| 86 | Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow: |
| 87 | |
| 88 | 1. Maintainer decides a feature request is out of scope |
| 89 | 2. Check if a matching `.out-of-scope/` file already exists |
| 90 | 3. If yes: append the new issue to the "Prior requests" list |
| 91 | 4. If no: create a new file with the concept name, decision, reason, and first prior request |
| 92 | 5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file |
| 93 | 6. Close the issue with the `wontfix` label |
| 94 | |
| 95 | ## Updating or removing out-of-scope files |
| 96 | |
| 97 | If the maintainer changes their mind about a previously rejected concept: |
| 98 | |
| 99 | - Delete the `.out-of-scope/` file |
| 100 | - The skill does not need to reopen old issues — they're historical records |
| 101 | - The new issue that triggered the reconsideration proceeds through normal triage |
| 102 |