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.