Skip to main content

Pre-ADR Create Hook

Purpose​

Validates the ADR creation request before the workflow executes. Prevents duplicate ADRs and ensures topic quality.

Trigger​

Fires automatically before /adr-decision command execution.

Validation Steps​

1. Topic Validation​

def validate_topic(topic: str) -> tuple[bool, str]:
    """Validate ADR topic is meaningful."""
    if len(topic) < 10:
        return False, "Topic too short. Provide more detail."

    if len(topic) > 200:
        return False, "Topic too long. Be more concise."

    # Check for question format
    question_words = ['how', 'what', 'which', 'should', 'can']
    has_question = any(topic.lower().startswith(w) for w in question_words)

    if not has_question and '?' not in topic:
        return True, "Consider phrasing as a question for clarity."

    return True, "Topic validated."

2. Duplicate Check​

def check_duplicates(topic: str, adr_dir: str) -> list[str]:
    """Find potentially duplicate ADRs."""
    import os
    from difflib import SequenceMatcher

    duplicates = []
    topic_lower = topic.lower()

    for root, dirs, files in os.walk(adr_dir):
        for file in files:
            if file.endswith('.md') and file.startswith('ADR-'):
                # Extract title from filename
                title = file.replace('.md', '').split('-', 2)[-1].replace('-', ' ')

                # Check similarity
                ratio = SequenceMatcher(None, topic_lower, title.lower()).ratio()
                if ratio > 0.6:  # 60% similar
                    duplicates.append(f"{file} ({ratio:.0%} similar)")

    return duplicates

3. Category Validation​

VALID_CATEGORIES = [
    'cloud-platform',
    'security',
    'core',
    'frontend',
    'backend',
    'infrastructure',
    'data'
]

def validate_category(category: str) -> tuple[bool, str]:
    """Validate ADR category exists."""
    if category in VALID_CATEGORIES:
        return True, f"Category '{category}' is valid."

    return False, f"Invalid category. Use one of: {', '.join(VALID_CATEGORIES)}"

Hook Output​

{
  "proceed": true,
  "warnings": ["Consider phrasing as a question"],
  "errors": [],
  "suggestions": {
    "similar_adrs": ["ADR-003-authentication-strategy.md (65% similar)"],
    "recommended_category": "security"
  }
}

Configuration​

# In .coditect/hooks.yaml
pre-adr-create:
  enabled: true
  similarity_threshold: 0.6
  require_question_format: false
  block_on_duplicate: false  # Warn but allow

Integration​

Called automatically by /adr-decision command before Phase 1 (Research).

# In adr-decision command execution
hook_result = run_hook('pre-adr-create', {
    'topic': user_topic,
    'category': category,
    'adr_dir': 'internal/architecture/adrs/'
})

if not hook_result['proceed']:
    print("ADR creation blocked:")
    for error in hook_result['errors']:
        print(f"  - {error}")
    return

if hook_result['warnings']:
    print("Warnings:")
    for warning in hook_result['warnings']:
        print(f"  - {warning}")

Last Updated: 2025-12-29