Out-of-Scope Knowledge Base

超出范围知识库

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

仓库中的 .out-of-scope/ 目录存储被拒绝功能请求的持久记录。它有两个用途：

Institutional memory — why a feature was rejected, so the reasoning isn't lost when the issue is closed
Deduplication — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it

组织记忆——功能为何被拒绝，这样当 issue 关闭时理由不会丢失
去重——当新 issue 与先前的拒绝匹配时，技能可以展示之前的决策，而不是重新争论

Directory structure

目录结构

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

.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.

每个概念一个文件，而非每个 issue 一个文件。请求相同内容的多个 issue 归入同一文件。

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"

# Dark Mode（深色模式）

本项目不支持深色模式或面向用户的主题定制。

## 为什么这超出了范围

渲染管线假定在 `ThemeConfig` 中定义单一调色板。
支持多个主题将需要：

- 包装整个组件树的主题上下文提供者
- 每个组件的主题感知样式解析
- 用户主题偏好的持久化层

这是一个重大的架构变更，与项目专注于内容创作的方向不符。
主题化是嵌入或重新分发输出的下游消费者关心的问题。

```ts
// 当前的 ThemeConfig 接口并非为运行时切换而设计：
interface ThemeConfig {
  colors: ColorPalette; // 单一调色板，在构建时解析
  fonts: FontStack;
}
```

## 先前的请求

- #42 — "添加深色模式支持"
- #87 — "无障碍夜间主题"
- #134 — "深色主题选项"

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.

为概念使用简短、描述性的 kebab-case 名称：dark-mode.md、plugin-system.md、graphql-api.md。名称应足够可识别，使得浏览目录的人无需打开文件就能理解被拒绝的是什么。

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...")

项目范围或理念（"本项目专注于 X；主题化是下游关注点"）
技术约束（"支持这个需要 Y，这与我们的 Z 架构冲突"）
战略决策（"我们选择使用 A 而不是 B，因为……"）

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/`

何时检查 `.out-of-scope/`

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

在分诊期间（步骤 1：收集上下文），读取 .out-of-scope/ 中的所有文件。在评估新 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?"

检查请求是否匹配现有的超出范围概念
匹配是按概念相似度，而非关键词——"夜间主题"匹配 dark-mode.md
如果有匹配，向维护者展示："这与 .out-of-scope/dark-mode.md 相似——我们之前拒绝过，因为[理由]。你仍然这么认为吗？"

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

确认——新 issue 被添加到现有文件的"先前请求"列表，然后关闭
重新考虑——超出范围文件被删除或更新，issue 通过正常分诊流程继续
不同意——这些 issue 相关但不同，按正常分诊继续

When to write to `.out-of-scope/`

何时写入 `.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.

仅当enhancement（而非 bug）被拒绝为 wontfix 时。这同样适用于 enhancement PR——被拒绝的 PR 在此记录，这样相同的请求不会以新代码的形式再次出现。

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.

不要在因已实现而关闭为 wontfix 时写入此处。那是已构建的功能，而非被拒绝的；记录它会用错误的拒绝污染去重检查。取而代之，关闭评论指向该功能已存在的位置。

The flow:

流程：

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

维护者决定功能请求超出范围
检查匹配的 .out-of-scope/ 文件是否已存在
如果是：将新 issue 追加到"Prior requests"列表
如果否：使用概念名称、决策、理由和第一个先前请求创建新文件
在 issue 上发布评论解释决策并提及 .out-of-scope/ 文件
使用 wontfix 标签关闭 issue

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

删除 .out-of-scope/ 文件
技能不需要重新打开旧的 issue——它们是历史记录
触发重新考虑的新 issue 通过正常分诊流程继续