abildtoft/kramme:docs:out-of-scope

Out-of-Scope Knowledge Base

Maintain a .out-of-scope/ directory at the project root: one short markdown file per rejected enhancement concept, capturing what was rejected and why so future sessions can check before re-litigating.

When to use

Use this skill when:

• The team has just rejected an enhancement during discovery, triage, refactor planning, or review and wants to record the rejection so it does not get re-proposed in six months.
• A new request arrives and you suspect it has been rejected before — check looks up matches by concept similarity.
• A previously-rejected concept is being re-proposed with new evidence — append records the new request alongside the original.
• Priorities have changed and a prior rejection no longer applies — reconsider removes the entry.

Route elsewhere if:

• Bug rejection → close the issue as wontfix with a comment. This skill is for enhancement scope, not bug triage.
• Deferral ("not now, but maybe later") → use issue priority/status. A deferral is not a settled rejection, and record will gate on this distinction.
• Architectural decision with rejected alternatives → use /kramme:docs:adr, which preserves rejected alternatives inside the ADR itself.
• In-project decisions during a tracked SIW initiative → use /kramme:siw:close's decision log.

Argument parsing

1. Parse $ARGUMENTS by spaces. The first token is the subcommand.
2. Recognize record, check, append, reconsider as exclusive subcommands.
3. The remaining tokens form the concept. For append, the last token is the issue reference and the rest form the concept — but only when the last token looks like an issue reference (#123, ABC-123, or a URL). If it does not (e.g. append dark mode), treat all remaining tokens as the concept and ask the user for the issue reference instead of guessing.
4. If no arguments are given or the subcommand is unknown, print the supported subcommands and stop.

Slug rule

Lowercase, replace spaces and underscores with hyphens, strip characters outside [a-z0-9-], collapse repeated hyphens. Example: "Dark Mode" → dark-mode. The skill always keys files by slug; the user-facing concept name is preserved verbatim inside the file body.

If the computed slug is empty (the concept was missing or contained no usable characters), print an error naming the offending input and stop before any file operation. This guard applies to every subcommand, including append when the concept token is missing.

Subcommands

record <concept>

Capture a settled rejection.

1. Slug the concept.

2. If .out-of-scope/<slug>.md already exists, ask whether the user meant append. Stop unless overridden.

3. Settled-vs-deferral gate — ask the user (via the structured question tool when available, otherwise in plain prose) and wait for an explicit choice:

   header: "Is this a settled rejection?"
   question: "Recording a rejection here means future sessions will surface it before re-litigating. Is this a settled decision, or a deferral that might come back later?"
   options:
     - "Settled rejection — record it"
     - "Deferral — cancel"
   

   If the user picks deferral, stop without writing.

4. Gather rejection content from the user in prose — these are free-text fields, not multiple choice, so do not use AskUserQuestion here. Pull from the surrounding conversation where the answer is already known and ask for the rest:

   • Substantive reason (project scope, technical constraints, or strategic decision; not "we're too busy").
   • Optional code sample illustrating a technical constraint.
   • Prior-request references (issue links or PR references that triggered or shaped the rejection).
   • Decider name or role.

5. Create the directory if missing (mkdir -p .out-of-scope).

6. Render and write .out-of-scope/<slug>.md from assets/out-of-scope-template.md:

   • {Concept Name} → user-facing concept (preserve original casing, not the slug).
   • {YYYY-MM-DD} → today's absolute date. Capture the date in the file body so git mv, re-checkout, or copy operations cannot reset it via mtime.
   • {name or role} → decider.
   • "Why this is out of scope" → substantive reason.
   • "Prior requests" → bullet list of issue references with one-line context each.

7. If .gitignore would hide .out-of-scope/, ask once per record run (via the structured question tool when available, otherwise in plain prose — wait for an explicit choice) whether to keep it gitignored or remove the ignore rule. Default recommendation: committed (institutional memory).

8. Print recorded .out-of-scope/<slug>.md.

check <concept>

Look up whether a concept has been rejected before.

1. If .out-of-scope/ is missing or empty, print no prior rejections recorded and stop.

2. List filenames in .out-of-scope/ (ls .out-of-scope/).

3. Reason about which slugs plausibly match the concept. Concept similarity is judgmental, not fuzzy: dark-mode and night-theme plausibly match; dark-mode and darken-image-filter do not.

4. For each plausible match, read the file body and surface:

   This is similar to `.out-of-scope/<slug>.md` (decided <date>) — we rejected this before because <one-line summary of "Why this is out of scope">. Continue, or honor the prior rejection?
   

5. Ask the user (via the structured question tool when available, otherwise in plain prose) and wait for an explicit choice:

   header: "Honor prior rejection?"
   question: "<surface format above>"
   options:
     - "Honor the prior rejection — stop"
     - "Continue anyway"
   

   If continuing, note the prior rejection in subsequent output so callers can see the override.

6. If no plausible match, print no prior rejections found for <concept>.

append <concept> <issue-ref>

Record an additional request that asked for an already-rejected concept.

1. Slug the concept; locate .out-of-scope/<slug>.md.
2. If absent, ask whether the user meant record. Stop unless overridden.
3. If <issue-ref> already appears under "Prior requests", print <issue-ref> already recorded in .out-of-scope/<slug>.md and stop — re-running must not duplicate bullets.
4. Otherwise append a new bullet under the "Prior requests" heading: - <issue-ref> — <short context>. Ask for the short context if not provided.
5. Print appended <issue-ref> to .out-of-scope/<slug>.md.

reconsider <concept>

Remove a rejection that no longer applies.

1. Slug the concept; locate .out-of-scope/<slug>.md.

2. If absent, print no rejection recorded for <concept> and stop.

3. Read the file and surface its content so the user sees what is being removed.

4. Confirm with the user (via the structured question tool when available, otherwise in plain prose) and wait for an explicit choice:

   header: "Remove this rejection?"
   question: "Removing means future sessions will no longer surface it. Continue?"
   options:
     - "Remove"
     - "Keep"
   

5. If confirmed, delete the file. Print removed .out-of-scope/<slug>.md — rejection no longer recorded.

6. Reopening the original issue is a separate action — this skill does not touch Linear or git history.

File format

Files in .out-of-scope/ follow the canonical structure in assets/out-of-scope-template.md — the single source of truth; read it before rendering. The load-bearing elements, in order:

1. # {Concept Name} — the first heading; check matches against it.
2. Decided: {YYYY-MM-DD} Decided by: {name or role} — date and decider on one line.
3. ## Why this is out of scope — the substantive reason, plus an optional code sample.
4. ## Prior requests — the bullet list append grows.

check looks up files by slug and first-heading match; append locates the "Prior requests" list by heading. Manual edits must preserve heading text and order.

Reading guidance for consuming skills

Skills that read .out-of-scope/ during their context-gathering phase — discovery, issue-definition, and refactor-planning skills among them — each carry their own inline instruction so they stay self-contained when this skill is missing. The shared protocol they follow:

1. Cheap-list filenames first. Run ls .out-of-scope/ (or equivalent). If absent or empty, skip silently.
2. Read file bodies only on plausible match. Concept similarity is judgmental, not fuzzy. Read at most a handful of files per session.
3. Surface format: This is similar to .out-of-scope/<slug>.md (decided <date>) — we rejected this before because <one-line summary>. Continue, or honor the prior rejection?
4. User is the gate. Never auto-fail; ask the user (via the structured question tool when available, otherwise in plain prose) and let them override.

Verification

• .out-of-scope/<slug>.md is created with the canonical template after record.
• Decided: line in the file body is today's absolute date (not just file mtime).
• check surfaces matches by concept similarity, not by exact slug equality only.
• append grows the "Prior requests" list by one bullet per new issue reference; a duplicate reference is rejected, not re-appended.
• An empty slug (missing or fully stripped concept) errors out before any file operation.
• reconsider deletes the matching file and prints a confirmation.