T-CPAH-check-skill-docs-require-mmdc-flag

Status: closed/obsoleted · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

check_skill_docs.py today exits 2 (“script-itself-failed”) when mmdc is absent and --skip-mermaid is not set. The eval runner (tests/run_skill_doc_evals.py) maps the absent-binary case to a SKIP (counted as pass) so local dev on a host without Node doesn’t block. The same SKIP semantics in CI would silently let a regression land if no CI host had mmdc. A --require-mmdc flag would let CI opt into hard-fail-on-missing semantics while local dev keeps the soft-skip default.

Today

.claude/skills/project-check/check_skill_docs.py argparse exposes --skip-mermaid (bypass mermaid step entirely) but not --require-mmdc. The script’s default behavior when mmdc is missing is exit 2 with a stderr install hint — which /project-check would surface, but CI runners that haven’t installed Node treat exit 2 the same as the SKIP path in the eval runner.

Cited in T-BLFH-extend-project-check-with-skill-doc-lint-suite’s post-mortem:

The eval runner skips mermaid-requiring cases when mmdc is absent (counted as pass, with a SKIP line). That keeps CI on hosts without Node from breaking, but it also means a regression could silently land if every CI host happens to lack mmdc. A --require-mmdc flag for CI would tighten the contract.

Proposed

check_skill_docs.py accepts a --require-mmdc flag. When set, an absent mmdc binary causes exit 1 (gate failure) instead of exit 2 (script-error-skip-able). The eval runner gains a parallel --require-mmdc passthrough so CI invocations can demand the binary is present. Local invocations without the flag preserve today’s behavior.

Approach

1. Add --require-mmdc to check_skill_docs.py’s argparse. When set and mmdc is None after resolution, return 1 with a clear error message naming the install command.
2. Add --require-mmdc to tests/run_skill_doc_evals.py’s argparse and forward to the docs-check sub-process.
3. Update the project-check SKILL.md to mention the flag in “Step 1b” guidance for CI invocations.

Files to touch

Location	Kind	Change
.claude/skills/project-check/check_skill_docs.py	modify	add the flag,
.claude/skills/project-check/tests/run_skill_doc_evals.py	modify	add
.claude/skills/project-check/SKILL.md	modify	mention the flag in the

Acceptance criteria

• AC-1: check_skill_docs.py --require-mmdc exits 1 (not 2) on a host without mmdc on PATH, with a clear install hint in the stderr output.
• AC-2: check_skill_docs.py without --require-mmdc continues to exit 2 in the same case (today’s behavior).
• AC-3: run_skill_doc_evals.py --require-mmdc propagates the flag and surfaces a FAIL instead of a SKIP for mermaid-required cases on a host without mmdc.

Out of scope

• Auto-installing mmdc — same exclusion as the parent task.
• Generalising --require-<binary> to other dependencies; do it on the second motivating example.

Dependencies

• none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-BLFH-extend-project-check-with-skill-doc-lint-suite on 2026-05-21.

---

← Back to Tasks