impl-standards

Implementation Standards

Apply these standards during implementation to ensure consistent, maintainable code.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• During /itp:go Phase 1
• When writing new production code
• User mentions "error handling", "constants", "magic numbers", "progress logging", "SSoT", "dependency injection", "config singleton"
• Before release to verify code quality

Quick Reference

Standard	Rule
Errors	Raise + propagate; no fallback/default/retry/silent
Constants	Abstract magic numbers into semantic, version-agnostic dynamic constants
SSoT/DI	Config singleton → None-default + resolver → entry-point validation
Dependencies	Prefer OSS libs over custom code; no backward-compatibility needed
Progress	Operations >1min: log status every 15-60s
Logs	logs/{adr-id}-YYYYMMDD_HHMMSS.log (nohup)
Metadata	Optional: catalog-info.yaml for service discovery

---

Error Handling

Core Rule: Raise + propagate; no fallback/default/retry/silent

# ✅ Correct - raise with context
def fetch_data(url: str) -> dict:
    response = requests.get(url)
    if response.status_code != 200:
        raise APIError(f"Failed to fetch {url}: {response.status_code}")
    return response.json()

# ❌ Wrong - silent catch
try:
    result = fetch_data()
except Exception:
    pass  # Error hidden

See Error Handling Reference for detailed patterns.

---

Constants Management

Core Rule: Abstract magic numbers into semantic constants

# ✅ Correct - named constant
DEFAULT_API_TIMEOUT_SECONDS = 30
response = requests.get(url, timeout=DEFAULT_API_TIMEOUT_SECONDS)

# ❌ Wrong - magic number
response = requests.get(url, timeout=30)

See Constants Management Reference for patterns.

---

Progress Logging

For operations taking more than 1 minute, log status every 15-60 seconds:

import logging
from datetime import datetime

logger = logging.getLogger(__name__)

def long_operation(items: list) -> None:
    total = len(items)
    last_log = datetime.now()

    for i, item in enumerate(items):
        process(item)

        # Log every 30 seconds
        if (datetime.now() - last_log).seconds >= 30:
            logger.info(f"Progress: {i+1}/{total} ({100*(i+1)//total}%)")
            last_log = datetime.now()

    logger.info(f"Completed: {total} items processed")

---

Log File Convention

Save logs to: logs/{adr-id}-YYYYMMDD_HHMMSS.log

# Running with nohup
nohup python script.py > logs/2025-12-01-my-feature-20251201_143022.log 2>&1 &

---

---

Data Processing

Core Rule: Prefer Polars over Pandas for dataframe operations.

Scenario	Recommendation
New data pipelines	Use Polars (30x faster, lazy eval)
ML feature eng	Polars → Arrow → NumPy (zero-copy)
MLflow logging	Pandas OK (add exception comment)
Legacy code fixes	Keep existing library

Exception mechanism: Add at file top:

# polars-exception: MLflow requires Pandas DataFrames
import pandas as pd

See ml-data-pipeline-architecture for decision tree and benchmarks.

---

Related Skills

Skill	Purpose
adr-code-traceability	Add ADR references to code
code-hardcode-audit	Detect hardcoded values before release
ml-data-pipeline-architecture	Polars/Arrow efficiency patterns

---

Reference Documentation

• Error Handling - Raise + propagate patterns
• Constants Management - Magic number abstraction
• SSoT / Dependency Injection - Config singleton → None-default → resolver chain

---

Troubleshooting

Issue	Cause	Solution
Silent failures	Bare except blocks	Catch specific exceptions, log or re-raise
Magic numbers in code	Missing constants	Extract to named constants with context
Error swallowed	except: pass pattern	Log error before continuing or re-raise
Type errors at runtime	Missing validation	Add input validation at boundaries
Config not loading	Hardcoded paths	Use environment variables with defaults

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.