1# Out-of-Scope Knowledge Base
2 
3The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
4 
51. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
62. **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 
17One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
18 
19## File format
20 
21The 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 
26This project does not support dark mode or user-facing theming.
27 
28## Why this is out of scope
29 
30The 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 
37This is a significant architectural change that doesn't align with the
38project's focus on content authoring. Theming is a concern for downstream
39consumers who embed or redistribute the output.
40 
41```ts
42// The current ThemeConfig interface is not designed for runtime switching:
43interface 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 
58Use 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 
62The 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 
68The 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 
72During 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 
78The 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 
86Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow:
87 
881. Maintainer decides a feature request is out of scope
892. Check if a matching `.out-of-scope/` file already exists
903. If yes: append the new issue to the "Prior requests" list
914. If no: create a new file with the concept name, decision, reason, and first prior request
925. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
936. Close the issue with the `wontfix` label
94 
95## Updating or removing out-of-scope files
96 
97If 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