Skip to content

adamayoung/TMDb / .claude/skills/diagnose-ci-failure

diagnose-ci-failure

Verified

Diagnose a failing CI workflow run (lint, markdown lint, build, or unit tests) — identify which job failed, the cause, and a concrete fix

FileKindSize
SKILL.mdskill md6.2 KB
references/_index.mdmarkdown2.5 KB
references/build.mdmarkdown3.4 KB
references/lint.mdmarkdown4.9 KB
references/linux.mdmarkdown2.7 KB
references/markdown.mdmarkdown2.9 KB
references/unit-tests.mdmarkdown3.4 KB

references/markdown.md

View on GitHub
# Lint Markdown job failure (markdownlint)

The **Lint Markdown** job runs in the
`ghcr.io/igorshubovych/markdownlint-cli:v0.48.0` container and lints:

```bash
markdownlint "README.md" "CLAUDE.md" "**/*.docc/**/*.md" ".claude/**/*.md" "knowledge/**/*.md" ".github/*.md"
```

Six path groups: `README.md`, `CLAUDE.md`, DocC catalog markdown
(`Sources/**/*.docc/**/*.md`), **every skill and agent file under `.claude/`**,
**the knowledge base under `knowledge/`**, and the top-level `.github/*.md`
specs (`CODE_REVIEW.md`, `ISSUE_FILING.md`) — the `.claude/` and `knowledge/`
groups are the most frequently edited, so a failure here is most often a skill
edit or a captured entry, not a README one. The job runs only when the
`markdown` paths filter matched one of those, or on `workflow_dispatch`.

`knowledge/skill-improvement-log.md` carries a scoped
`<!-- markdownlint-disable-file MD001 -->`: its entries are dated `###` headings
with no `##` sections, which is the documented log shape. That is the only
per-file exemption — don't add more without saying why in the file.

Config is `.markdownlintrc`, shared by all six groups. Note **`MD013`
(line-length) and `MD041` (first-line heading) are disabled**, so neither can
be the cause — don't start there.

## Reading the failure

markdownlint emits `file:line[:col] MD0xx/rule-name <message>`. The `MD0xx`
code maps to a rule; common ones in this repo:

- **MD024** duplicate heading — two headings with the same text in one file.
- **MD031 / MD032** — fenced code blocks / lists need surrounding blank lines.
- **MD040** — fenced code block missing a language (` ``` ` → ` ```swift `/` ```text `).
Configuration is `.markdownlintrc` at the repo root. It **disables** `MD013`
(line length), `MD033` (inline HTML), `MD041` (first-line heading) and `MD060`,
and scopes `MD024` (duplicate heading) to siblings only — so none of those can
be the failure. Read it before assuming a default limit applies.

## Common causes & fixes

- **A skill or agent file under `.claude/`** — the most common cause, since this
  repo edits those constantly. Usually MD040 (fence with no language) or
  MD031/MD032 (missing blank line around a fence or list).
- **A DocC `.md` you edited** (service extension file, `TMDb.md`, `TMDbClient.md`)
  introduced a missing code-fence language or a duplicate sibling heading.
  Fix the flagged `file:line` to satisfy the rule.
- **`README.md` or `CLAUDE.md` edits** — same rules; watch MD040 fence
  languages in examples.

## Reproduce locally

```bash
make lint-markdown
```

(lints the same file set as CI's `Lint Markdown` step, split across five
`markdownlint` invocations — `Makefile`, target `lint-markdown` — where CI
passes all six globs to one). Fix, re-run until clean.

## Output

**Summary:** Lint Markdown — `MD0xx` at `file:line`.
**Cause:** the rule violation in the changed README / `CLAUDE.md` / DocC /
`.claude/` file.
**Fix:** correct the flagged line; re-run `make lint-markdown`.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall