Agent Skills: Technical.md Validator

Technical.md Validator

Analyze a Technical.md file and identify rules that may be ineffective, vague, or redundant with existing tooling.

Workflow

Step 1: Locate Technical.md

Find the Technical.md file to validate:

1. If path argument provided → use that path
2. Check ./Technical.md
3. Check ./.candid/Technical.md

If no file found:

❌ No Technical.md found.

Looked in:
- ./Technical.md
- ./.candid/Technical.md

Create one with: /candid-init

Step 2: Detect Linter Configs

Check for existing linter configurations:

# JavaScript/TypeScript
ls .eslintrc* eslint.config.* .prettierrc* biome.json 2>/dev/null

# Python
ls .flake8 pyproject.toml setup.cfg .ruff.toml ruff.toml 2>/dev/null

# Go
ls .golangci.yml .golangci.yaml 2>/dev/null

# Ruby
ls .rubocop.yml 2>/dev/null

Store detected linters for Step 4.

Step 3: Parse Technical.md

Read the Technical.md file and extract rules.

Rule detection:

• Lines starting with - or * (list items)
• Lines starting with numbers (numbered lists)
• Lines following a ## heading

Skip:

• Code blocks (between ```)
• Empty lines
• Comments (HTML or markdown)
• Heading lines themselves

Store each rule with:

• Line number
• Section heading it belongs to
• Full rule text

Step 4: Validate Each Rule

Check each rule against these issue categories:

4.1 Vague Language (🌫️)

Flag rules containing vague terms without specifics:

| Vague Term | Why It's Vague | |------------|----------------| | "clean" | Subjective, no definition | | "good" | Subjective | | "proper" / "appropriate" | Undefined standard | | "well-designed" / "well-structured" | No criteria | | "readable" / "maintainable" | Without metrics | | "best practices" | Circular reference | | "when necessary" / "when appropriate" | Undefined trigger | | "avoid" (alone) | No guidance on alternatives | | "consider" | Not a requirement |

Also flag: suitable, adequate, well-organized, well-written, scalable, flexible, robust, simple, straightforward, intuitive, obvious, sensible, meaningful, significant, as needed, prefer, try to, minimal, few, some, many, several, various.

Exception: Terms are OK if followed by specific criteria:

• "readable (functions under 50 lines)" ✓
• "maintainable" ✗

4.2 Missing Thresholds (📏)

Flag rules that imply quantity without numbers:

| Pattern | Issue | |---------|-------| | "small functions" | How small? | | "short methods" | How short? | | "limit parameters" | To how many? | | "minimal dependencies" | What's minimal? | | "few levels of nesting" | How few? | | "reasonable timeout" | What's reasonable? |

Also flag: maximum/minimum, too many/too few, keep under/below, no more than — when no number follows.

Fix pattern: Add specific numbers (e.g., "functions under 50 lines")

4.3 Linter Overlap (🔧)

Flag rules that linters typically handle (based on Step 2):

If ESLint/Prettier detected:

• Semicolon usage
• Quote style (single vs double)
• Indentation rules
• Trailing commas
• Import ordering
• Unused variables
• No console.log

If Flake8/Ruff detected:

• Line length
• Import sorting
• Whitespace rules
• Naming conventions (snake_case)

If any linter detected:

• Formatting rules in general
• Basic syntax style

4.4 Multiple Concerns (🎯)

Flag rules that try to do too much:

• Rules with "and" connecting unrelated concerns
• Rules over 2 lines long
• Rules with multiple "must" statements

Example:

❌ "Functions should be small, well-documented, and handle errors properly"
✓ Split into three rules

4.5 Unverifiable Rules (❓)

Flag rules that can't be checked by reading code:

• "Think about edge cases"
• "Be consistent"
• "Follow team conventions"
• "Use common sense"
• References to external documents without specifics

4.6 Codebase Spot-Check (🔬)

For up to 10 rules that cite a path, glob, or naming pattern:

1. Verify every cited file/directory exists (ls it). Missing → flag stale.
2. Sample 3 files the rule applies to (find/grep by the rule's stated scope) and check whether the rule actually holds in each.
3. 0/3 hold → flag untrue ("rule contradicts this codebase — remove or move to Gaps"). 1-2/3 hold → flag contested ("add known exceptions or relax the rule"). Report in a 🔬 Spot-Check section listing the sampled files per rule.

Step 5: Generate Report

Present findings organized by severity:

# Technical.md Validation Report

**File:** ./Technical.md
**Rules analyzed:** [N]
**Issues found:** [M]

---

## 🔴 Critical Issues

Rules that won't be effective in reviews.

### 🌫️ Vague Language

| Line | Rule | Issue |
|------|------|-------|
| 12 | "Write clean code" | "clean" is subjective |
| 24 | "Use appropriate error handling" | "appropriate" undefined |

### 📏 Missing Thresholds

| Line | Rule | Issue |
|------|------|-------|
| 18 | "Keep functions small" | No size specified |
| 31 | "Limit nesting depth" | No depth specified |

---

## 🟡 Warnings

Rules that may have issues.

### 🔧 Linter Overlap

| Line | Rule | Linter |
|------|------|--------|
| 8 | "Use semicolons" | ESLint handles this |
| 15 | "Sort imports alphabetically" | Prettier/ESLint handles this |

### 🎯 Multiple Concerns

| Line | Rule | Suggestion |
|------|------|------------|
| 22 | "Functions should be pure, small, and documented" | Split into 3 rules |

---

## 🔬 Spot-Check

[Per rule checked: verdict (stale/untrue/contested) with the 3 sampled files]

---

## ✅ Good Rules

[List of rules that passed validation]

If zero issues: output a short pass message with file path and rule count instead of the full report.

Step 6: Suggest Fixes (if --fix flag)

If --fix argument provided, include specific rewrites:

## 💡 Suggested Rewrites

### Line 24: "Use appropriate error handling"
**Original:** Use appropriate error handling
**Suggested:**
- All async functions must have try/catch or .catch()
- Errors must be logged with context before re-throwing
- User-facing errors must not expose stack traces

Step 7: Summary

End with actionable summary:

---

## Summary

- **[X] rules** are effective and specific ✅
- **[Y] rules** need thresholds or specifics 📏
- **[Z] rules** overlap with linters 🔧
- **[W] rules** are too vague to enforce 🌫️

### Recommended Actions

1. Remove [Z] linter-overlap rules (your linter handles these)
2. Add numbers to [Y] threshold rules
3. Rewrite [W] vague rules with specific criteria

Run `/candid-validate-standards --fix` for suggested rewrites.

Remember

The goal is to help users write Technical.md files that:

1. Candid can actually enforce
2. Don't duplicate existing tooling
3. Focus on what matters (architecture, security, patterns)
4. Are specific enough to be useful

A validated Technical.md leads to better code reviews.