impl-standards_skill

Overview

This skill codifies core implementation standards to keep TypeScript services consistent, observable, and maintainable. It focuses on error handling, constants management, progress logging, data-processing choices, and log conventions used across releases. Use it to enforce predictable behavior and simplify code reviews and operational troubleshooting.

How this skill works

The skill prescribes concrete rules: always raise and propagate errors rather than silently swallowing them; replace magic numbers with named, version-agnostic constants; log long-running operations at regular intervals; and follow a standardized log file naming convention. It also recommends preferred libraries and exceptions for data pipelines and gives simple patterns developers can copy into production code. Apply the rules during implementation and before release to verify compliance.

When to use it

• When starting Phase 1 of a feature (/itp:go) or writing new production code
• If a PR touches error handling, constants, or progress logging
• Before release to audit code quality and operational readiness
• When adding or modifying data pipelines or dependencies
• When a service needs standardized logs for debugging or automation

Best practices

• Raise errors with contextual messages and let callers decide handling — avoid silent catches or default-swallowing
• Extract magic numbers into well-named constants with clear semantics and version-agnostic names
• For operations >1 minute, emit progress logs every 15–60 seconds to surface liveness and percent complete
• Prefer robust OSS libraries for common tasks; add documented exceptions where legacy or ecosystem constraints require alternatives
• Write logs to logs/{adr-id}-YYYYMMDD_HHMMSS.log when running background jobs (nohup style) for traceability

Example use cases

• A data ingestion job that must report progress and fail fast on upstream API errors
• Refactoring a module to remove magic numbers and centralize timeouts and thresholds
• Choosing Polars for a new ETL pipeline while documenting any Pandas exceptions required by downstream tooling
• Auditing a release branch to ensure no silent error handling or hidden retries remain
• Standardizing log filenames for automated collection and long-term retention