candid-validate-standards_skill

Overview

This skill validates a repository's Technical.md to find vague, ineffective, or redundant rules. It inspects rule wording, detects overlaps with configured linters, and reports missing thresholds or unverifiable guidance. The goal is a Practical, enforceable Technical.md that adds value beyond automated tooling.

How this skill works

The skill locates Technical.md (path argument, ./Technical.md, or ./.candid/Technical.md), reads and parses rules from lists and sections while skipping code blocks and comments, and collects each rule with its line number and heading. It detects present linters (ESLint/Prettier, Flake8/Ruff, golangci-lint, RuboCop) and validates each rule for vague language, missing numeric thresholds, linter overlap, multiple concerns, and unverifiability. It outputs an organized report with severity groups and optional suggested rewrites when --fix is provided.

When to use it

• When you want a Technical.md that is actionable and enforceable
• Before adopting repository-wide code standards or policy changes
• When reviews flag rules that seem subjective or redundant
• To audit a standards file after adding new linter tooling
• As part of CI checks to keep guidance precise and verifiable

Best practices

• Prefer concrete criteria (e.g., "functions under 50 lines") over subjective terms
• Remove formatting/style rules already enforced by linters
• Split multi-concern rules into separate, single-purpose statements
• Add numeric thresholds for quantitative guidance (limits, timeouts, sizes)
• Make rules verifiable by code or testing; avoid guidance that requires subjective judgement

Example use cases

• Scan a repo to detect rules that conflict with ESLint/Prettier and remove duplication
• Refine vague team standards into specific, automatable requirements
• Generate a prioritized report showing critical vague or unverifiable rules
• Produce suggested rewrites for maintainers with --fix to speed adoption
• Validate Technical.md before merging a contributing guide or policy change