Skip to content
contextlint

CTX-001 Placeholder detection

Overview

Section titled “Overview”

Validates that the body of a section is neither empty nor composed only of placeholders such as TODO, TBD, or WIP. Detected sections are reported as warning. The default placeholders are TBD / TODO / WIP / FIXME / N/A, and a single hyphen character (- / — / –) is also treated as “no content”.

Why it matters

Section titled “Why it matters”

While filling out a document template, it is easy to leave behind TODO: write later or TBD, switch to another task, and forget to come back. Drafts produced by AI also tend to ship with these kinds of placeholders. Markdown stays valid, so markdownlint and CI pass, but the document is unfinished. This rule detects those “easily missed unfinished sections”.

Options

Section titled “Options”
FieldTypeRequiredDescription
sectionstring—Restrict validation to a specific section (exact heading match)
placeholdersstring[]—Array of strings to treat as placeholders. When set, overrides the defaults (does not extend them)
filesstring—Glob of files this rule applies to

Detection is case-insensitive and checks whether the trimmed body equals an entire placeholder. The rule does not flag the word TODO mixed into prose.

Bad example

Section titled “Bad example”
## Overview


This document ...


## Design approach


TBD


## Impact


-

Design approach contains only the placeholder TBD, and Impact contains only - and is treated as having no content. Both trigger violations.

docs/design.md
  line 7   warning  Section "Design approach" contains only placeholder "TBD"  CTX-001
  line 11  warning  Section "Impact" contains only placeholder "-"             CTX-001

When a section body is completely empty, the message looks like this:

docs/design.md
  line 7  warning  Section "Design approach" has no content  CTX-001

After fix

Section titled “After fix”
## Overview


This document ...


## Design approach


The new authentication flow adopts OAuth 2.0 and migrates from the existing session-based authentication in stages.


## Impact


Affects every module under `packages/auth`.

Configuration example

Section titled “Configuration example”
{
  "rule": "ctx001",
  "options": {
    "section": "Design approach",
    "placeholders": ["TBD", "TODO", "Pending"],
    "files": "**/adr/*.md"
  }
}

When placeholders is set, it overrides the defaults. To keep the defaults and add domain-specific values like Pending, list both explicitly.

Section titled “Related rules”