standards-discovery

name	standards-discovery
description	Discovers and parses project coding standards, style guides, and architecture documentation. Searches for CONTRIBUTING, CODING_STANDARDS, STYLE_GUIDE, CONVENTIONS, ARCHITECTURE files and extracts rules for code review.
activation	Load before reviewing code or applying fixes in any project

Standards Discovery - Project Documentation Scanner

Discovers and parses project-specific coding standards, style guides, and architecture documentation to ensure code reviews align with project conventions.

---

Purpose

Before reviewing code, understand what standards the project follows:

• Naming conventions
• Architecture patterns
• Testing requirements
• Import rules
• Code organization

Project-specific rules always override generic best practices.

---

Discovery Workflow

Step 1: Search for Standards Files

ALWAYS run these searches first:

# Primary standards files
find . -type f \( \
  -iname "CONTRIBUTING*" -o \
  -iname "CODING*STANDARD*" -o \
  -iname "STYLE*GUIDE*" -o \
  -iname "CODE*STYLE*" -o \
  -iname "CONVENTIONS*" -o \
  -iname "ARCHITECTURE*" -o \
  -iname "GUIDELINES*" -o \
  -iname "DEVELOPMENT*" -o \
  -iname "STANDARDS*" \
\) -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.venv/*" -not -path "./vendor/*" 2>/dev/null

# Check docs directory
find ./docs -type f -name "*.md" 2>/dev/null

# Check .github directory
find ./.github -type f -name "*.md" 2>/dev/null

Step 2: Check Common Locations

Location	Priority	What to look for
CONTRIBUTING.md	HIGH	Code style, PR process, testing requirements
docs/ARCHITECTURE.md	HIGH	Layer structure, patterns used
docs/CODING_STANDARDS.md	HIGH	Naming, formatting, imports
.github/CONTRIBUTING.md	MEDIUM	Contribution guidelines
README.md	LOW	Development section
docs/	MEDIUM	Any .md files with style/standards

Step 3: Parse README for Standards Section

# Look for development/contributing sections in README
grep -n -i -A 20 "## Development\|## Contributing\|## Code Style\|## Standards\|## Guidelines" README.md 2>/dev/null

---

Standards Extraction

Naming Conventions

Look for patterns like:

# Search for naming convention mentions
grep -rni "naming convention\|camelCase\|snake_case\|PascalCase\|kebab-case\|UPPER_CASE" --include="*.md" --exclude-dir={.git,node_modules,.venv,vendor} . 2>/dev/null

Common patterns to identify:

• Classes: PascalCase / UpperCamelCase
• Functions/methods: snake_case / camelCase
• Constants: UPPER_SNAKE_CASE
• Variables: snake_case / camelCase
• Files: snake_case / kebab-case

Architecture Patterns

# Search for architecture mentions
grep -rni "clean architecture\|hexagonal\|DDD\|domain.driven\|layered\|SOLID\|microservice" --include="*.md" --exclude-dir={.git,node_modules,.venv,vendor} . 2>/dev/null

# Check for layer structure documentation
grep -rni "domain layer\|application layer\|infrastructure\|presentation layer\|use.case" --include="*.md" --exclude-dir={.git,node_modules,.venv,vendor} . 2>/dev/null

Common architectures to identify:

• Clean Architecture (layers: domain, application, infrastructure, presentation)
• Hexagonal Architecture (ports & adapters)
• DDD (aggregates, entities, value objects, repositories)
• Layered Architecture (presentation, business, data)

Testing Requirements

# Search for testing standards
grep -rni "test coverage\|unit test\|integration test\|pytest\|jest\|testing" --include="*.md" --exclude-dir={.git,node_modules,.venv,vendor} . 2>/dev/null

# Look for coverage requirements
grep -rni "coverage.*%\|minimum.*coverage\|100%\|80%\|90%" --include="*.md" --exclude-dir={.git,node_modules,.venv,vendor} . 2>/dev/null

Common requirements to identify:

• Minimum coverage percentage
• Required test types (unit, integration, e2e)
• Testing framework preferences
• Mocking guidelines

Import Rules

# Search for import guidelines
grep -rni "import\|absolute import\|relative import\|circular\|dependency" --include="*.md" --exclude-dir={.git,node_modules,.venv,vendor} . 2>/dev/null

Common rules to identify:

• Absolute vs relative imports
• Import ordering (stdlib, third-party, local)
• Circular dependency policy
• Dependency direction rules

---

Output Format

Generate a structured summary of discovered standards:

{
  "standards_found": true,
  "confidence": "HIGH|MEDIUM|LOW",
  "sources": [
    {
      "file": "CONTRIBUTING.md",
      "sections_found": ["Code Style", "Testing"]
    },
    {
      "file": "docs/ARCHITECTURE.md",
      "sections_found": ["Layer Structure", "DDD Patterns"]
    }
  ],
  "rules": {
    "naming": {
      "classes": "PascalCase",
      "functions": "snake_case",
      "constants": "UPPER_SNAKE_CASE",
      "variables": "snake_case",
      "files": "snake_case.py"
    },
    "architecture": {
      "pattern": "Clean Architecture",
      "layers": ["domain", "application", "infrastructure", "api"],
      "dependency_direction": "outer -> inner",
      "ddd_patterns": ["aggregates", "repositories", "value_objects"]
    },
    "testing": {
      "required": true,
      "min_coverage": "80%",
      "frameworks": ["pytest"],
      "types": ["unit", "integration"]
    },
    "imports": {
      "style": "absolute",
      "circular_allowed": false,
      "ordering": ["stdlib", "third_party", "local"]
    },
    "documentation": {
      "docstrings_required": true,
      "style": "Google"
    }
  },
  "explicit_rules": [
    "All public functions must have docstrings",
    "No business logic in infrastructure layer",
    "Use dataclasses for value objects"
  ],
  "warnings": [
    "No explicit naming convention found - using Python PEP 8 defaults"
  ]
}

---

Fallback: No Standards Found

If no explicit standards documentation exists:

1. Report as INFO:

   {
     "standards_found": false,
     "confidence": "LOW",
     "sources": [],
     "fallback": "Using industry best practices",
     "applied_defaults": {
       "python": "PEP 8, PEP 257",
       "typescript": "ESLint recommended, Prettier",
       "architecture": "General SOLID principles"
     }
   }
   

2. Check implicit standards from config files:

   # Ruff/flake8 config indicates Python style
   # Read pyproject.toml with Read tool and look for [tool.ruff] section
   
   # ESLint config indicates JS/TS style
   # Read .eslintrc.json with Read tool
   

3. Note in report:

   "No explicit coding standards documentation found. Review will use industry best practices. Consider creating CONTRIBUTING.md or docs/CODING_STANDARDS.md."

---

Integration with Code Review

After discovering standards, pass them to subsequent skills:

1. To linter-integration:

   • Which linter configs exist
   • Custom rules mentioned in docs

2. To architecture-analysis:

   • Architecture pattern (Clean/Hexagonal/DDD)
   • Layer structure
   • Dependency rules

3. To AI review:

   • Naming conventions
   • Documentation requirements
   • Testing requirements

---

Common Documentation Patterns

Python Projects

# Check for Python-specific docs
ls -la docs/*.md 2>/dev/null
# Read docs/development.md with Read tool

Common files:

• CONTRIBUTING.md
• docs/development.md
• docs/architecture.md
• pyproject.toml [tool.ruff] section

TypeScript Projects

# Check for TS-specific docs
ls -la docs/*.md 2>/dev/null
# Read CONTRIBUTING.md with Read tool

Common files:

• CONTRIBUTING.md
• docs/DEVELOPMENT.md
• .eslintrc.* (implicit style rules)
• tsconfig.json (implicit strictness level)

---

Red Flags - STOP if you

• Skip searching for standards files
• Assume no standards exist without searching
• Override explicit project rules with generic best practices
• Miss architecture documentation that defines layer boundaries

When these occur: Go back and complete the full discovery process.

---

Final Checklist

Before completing standards discovery, verify:

• Searched for standard documentation files (CONTRIBUTING, STYLE_GUIDE, etc.)
• Checked docs/ and .github/ directories
• Parsed README for development sections
• Extracted naming conventions (if documented)
• Identified architecture pattern (if documented)
• Found testing requirements (if documented)
• Noted import rules (if documented)
• Generated structured output with sources
• Flagged missing standards as INFO (not violations)