tomevault-io 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:goPhase 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 |
semantic-release |
Version management and release automation |
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:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- 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.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.