Linis

Linis — Filipino for "clean." Code and context files accumulate the residue of how they were built: a name here, a date there, a line quoting what someone said mid-session, a comment narrating an experiment instead of stating its settled result. None of that is wrong to have during a build — some of it is exactly what remember and the session-state file (the Minimal Banka block in AGENTS.md, core/progress.md, or context/progress-tracker.md, depending on tier) are supposed to capture while work is active. But once a version ships or a milestone closes, that residue stops being useful context and starts being clutter a future session has to read past to find what actually matters.

This skill does not touch correctness — it never changes what code does. It only changes how it's described.

Context Contract

Required: files changed in the current completed milestone, resolved from the session-state file and the version-control diff.

Conditional: a repo-wide scope, only if the user explicitly requests it · a narrower user-specified scope, respected in place of the default.

Excluded by default: files still under active work — this skill never runs against unsettled code, by design, regardless of requested scope.

Outputs: every proposed cleanup, listed for approval before any file is touched.

Write authority: only the confirmed settled file(s) in scope, and only narrative/descriptive content — operational history, provenance, compatibility facts, and load-bearing rationale are preserved, never removed.

Step 0 — Determine scope

Default: files changed in the current completed milestone, resolved from the session-state file and version-control diff. Do not expand this to a repo-wide cleanup unless the user explicitly requests that scope. If the user specifies a narrower scope, respect it.

Before reading project state, inspect AGENTS.md, the complete contents of CLAUDE.md, /core/, /context/, and the required tier files. Active schema 2 requires one complete Banka block in AGENTS.md containing these exact comments exactly once and in this order: <!-- BANKA:START -->, <!-- BANKA:STATE-SCHEMA: 2 -->, exactly one of <!-- BANKA:TIER: Minimal -->, <!-- BANKA:TIER: Core -->, or <!-- BANKA:TIER: Standard -->, then <!-- BANKA:END -->. The declared tier must match the filesystem shape and required files. CLAUDE.md must be exactly @AGENTS.md; if it is missing, schema 2 is still active for a runtime that discovers AGENTS.md directly, but report that Claude Code compatibility is unavailable.

A matching Minimal shape has neither /core/ nor /context/. Core has /core/ and its overview.md, architecture.md, design.md, and progress.md, with no /context/. Standard has /context/ and its project-overview.md, architecture.md, build-plan.md, code-standards.md, library-docs.md, ui-tokens.md, ui-rules.md, ui-registry.md, and progress-tracker.md, with no /core/.

Stop state-dependent work for competing authority, malformed/partial/duplicate or unknown Banka markers, a non-exact CLAUDE.md beside schema 2, an exact shim with missing authority, both state directories, tier mismatch, or missing required tier files. Do not choose, repair, or normalize any of these states.

Without valid schema 2, recognize legacy Banka state only when CLAUDE.md has the # Project Operating Protocol heading and exactly one complete legacy tier shape, with or without an old AGENTS block pointing to it. Legacy is compatibility-read-only: report that classification and inspect its state only to resolve scope and prepare the cleanup proposal. Applying a confirmed cleanup must not change a legacy Banka state file, tier marker, state directory, queue, or runtime shim; if the proposal would do so, stop until an explicitly requested, previewed, and confirmed migration completes. Incomplete legacy state or a broken old shim is a stop condition.

For active schema 2, Standard state is in /context/, Core state is in /core/, and Minimal state is in the Banka-owned AGENTS.md block. If neither schema 2 nor recognizable legacy state exists, treat the repository as unstructured rather than assuming Minimal; use the supplied milestone/diff to resolve scope and do not create Banka state files. If a confirmed Minimal cleanup changes AGENTS.md, edit only its Banka-owned block and preserve all content outside the block.

Never run this against active, in-progress work — check the session-state file first; if the scope includes something still marked in-progress, ask before touching it. Cleanup is for what's settled, not what's still being decided.

Step 1 — Scan for each offending pattern

For every file in scope, check for:

1. Names or identity references — the user's real name, a nickname, "the user," "as [X] mentioned," or any phrasing that identifies a specific person rather than describing a project decision. → Remove or generalize entirely. A decision reads as the project's decision, not a transcript of who said what.

2. Narrative dates — a timestamp attached to settled explanatory prose purely to mark when it was discussed, with no ongoing technical relevance. → Remove. Never remove dates from active operational structures such as Decisions Made, Session Notes, releases, migrations, compatibility records, or audit entries merely because they are dates. Keep any date that affects technical truth or traceability.

3. Direct quotes of the user's own words — anything in quotation marks attributing specific phrasing to the person. → Paraphrase into a settled, generalized statement, or remove if it adds nothing beyond flavor.

4. Present-tense "trying it out" framing — "let's see if this works," "testing whether," "trying this approach for now," anything that narrates an experiment in progress rather than stating its result. → If the experiment succeeded and is now the approach: restate as a settled fact, past tense, no hedging ("uses X because Y" not "trying X to see if Y works"). If it failed or was abandoned: remove entirely, unless the fact that it was tried and rejected has real forward value (see rule 6) — in which case compress to one settled sentence, not a narrative.

5. Elaborate, storytelling explanations — a comment or doc passage that walks through the reasoning at length, in a conversational voice, rather than stating the point directly. → Compress to the essential, authoritative statement. A comment justifies a non-obvious decision in one or two sentences; it does not narrate the thought process that arrived there.

6. Pure historical artifacts with no forward value — session logistics ("fixed a typo," "renamed a variable," "discussed X, decided to revisit later" with no later resolution ever recorded), one-off debugging notes about a problem now fully resolved, anything a future session gains nothing from reading. → Remove entirely. Preserve rejected approaches when forgetting them could repeat a security, correctness, compatibility, or architectural failure.

Step 2 — What to keep, unchanged in substance

• Settled decisions and their reasoning, restated as fact: past tense, declarative, no hedging, no attribution to a person — e.g. "Business Fund is always computed from Gross Profit, not revenue — a past audit found revenue-based computation was a copy-paste error, not a valid alternative," not "[User] pointed out on [date] that we should double check this, and after some back and forth we agreed..."
• Genuine "why" comments matching this project's own comment policy (see code-standards.md) — a non-obvious reason something is the way it is, stated briefly.
• Operational history: dated decisions, session handoffs, releases, migrations, compatibility constraints, audit trails, and unresolved issues.
• Provenance, attribution, licensing, and third-party authority records.
• Rejected alternatives whose rationale prevents a known regression or repeated failure.
• Anything already in a fully generalized, factual, past-tense form — leave it as-is, don't rewrite something that already passes.

Step 3 — Present before applying

Do not silently rewrite files. Show the proposed changes as a before/after diff or a clear list of "remove this / rewrite this to this," grouped by file, before touching anything:

## Linis — proposed cleanup

### [file]
- REMOVE: "[exact excerpt]" — [which rule triggered this]
- REWRITE: "[exact excerpt]" → "[proposed replacement]" — [which rule triggered this]

### [file]
...

[N] removals, [M] rewrites across [X] files. Apply?

Wait for confirmation. Then apply exactly what was shown — no additional changes introduced during application that weren't in the proposal.

Delegation note

Straightforward pattern-matching removals (a clearly narrative date, an obvious direct quote) are Junior-safe. Judgment calls about whether something is "merely historical" versus quietly load-bearing — especially inside a decision log, compatibility record, provenance note, or invariant's justification — are Senior-required; when genuinely unsure whether a passage matters, flag it in the proposal rather than guessing either direction.

The Rule

Code and docs should read like settled facts about the project, not a transcript of how the project came to believe them. Run this once a version ships or a milestone closes — not continuously, and never against work still in motion.