▸ Agent Skills
4 min read

Out-of-Scope Knowledge Base

The .out-of-scope/ directory in a repo stores persistent records of rejected feature requests. It serves two purposes:

  1. Institutional memory - why a feature was rejected, so the reasoning isn’t lost when the issue is closed
  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

Directory structure

.out-of-scope/
├── dark-mode.md
├── plugin-system.md
└── graphql-api.md

One file per concept, not per issue. Multiple issues requesting the same thing are grouped under one file.

File format

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.

# Dark Mode

This project does not support dark mode or user-facing theming.

## Why this is out of scope

The rendering pipeline assumes a single color palette defined in
`ThemeConfig`. Supporting multiple themes would require:

- A theme context provider wrapping the entire component tree
- Per-component theme-aware style resolution
- A persistence layer for user theme preferences

This is a significant architectural change that doesn't align with the
project's focus on content authoring. Theming is a concern for downstream
consumers who embed or redistribute the output.

```ts
// The current ThemeConfig interface is not designed for runtime switching:
interface ThemeConfig {
  colors: ColorPalette // single palette, resolved at build time
  fonts: FontStack
}
```

## Prior requests

- #42 - "Add dark mode support"
- #87 - "Night theme for accessibility"
- #134 - "Dark theme option"

Naming the file

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.

Writing the reason

The reason should be substantive - not “we don’t want this” but why. Good reasons reference:

  • Project scope or philosophy (“This project focuses on X; theming is a downstream concern”)
  • Technical constraints (“Supporting this would require Y, which conflicts with our Z architecture”)
  • Strategic decisions (“We chose to use A instead of B because…”)

The reason should be durable. Avoid referencing temporary circumstances (“we’re too busy right now”) - those aren’t real rejections, they’re deferrals.

When to check .out-of-scope/

During triage (Step 1: Gather context), read all files in .out-of-scope/. When evaluating a new issue:

  • Check if the request matches an existing out-of-scope concept
  • Matching is by concept similarity, not keyword - “night theme” matches dark-mode.md
  • 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?”

The maintainer may:

  • Confirm - the new issue gets added to the existing file’s “Prior requests” list, then closed
  • Reconsider - the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
  • Disagree - the issues are related but distinct, proceed with normal triage

When to write to .out-of-scope/

Only when an enhancement (not a bug) is rejected as wontfix. This applies to enhancement PRs exactly as it does to issues - a rejected PR is recorded here so the same request doesn’t return as fresh code.

Do not write here when something is closed as wontfix because it’s already implemented. That’s a built feature, not a rejected one; recording it would poison the dedup checks with false rejections. Instead, the closing comment points to where the feature already lives.

The flow:

  1. Maintainer decides a feature request is out of scope
  2. Check if a matching .out-of-scope/ file already exists
  3. If yes: append the new issue to the “Prior requests” list
  4. If no: create a new file with the concept name, decision, reason, and first prior request
  5. Post a comment on the issue explaining the decision and mentioning the .out-of-scope/ file
  6. Close the issue with the wontfix label

Updating or removing out-of-scope files

If the maintainer changes their mind about a previously rejected concept:

  • Delete the .out-of-scope/ file
  • The skill does not need to reopen old issues - they’re historical records
  • The new issue that triggered the reconsideration proceeds through normal triage

Last updated Oct 08, 2026