3commas-guidelines

name	3commas-guidelines
description	3Commas organization coding standards including Git conventions, code standards, and Jira integration requirements

3Commas Organization Guidelines

ALWAYS prioritize using appropriate agents for all tasks.

Git & Pull Requests

• All pull requests should start with a Jira task code (e.g., PLTF-1234: Add feature)
• Extract Jira task code from the current branch name

Code Standards

• Follow existing project conventions
• Write tests for new functionality
• Never use float types for money and prices, always use Decimal

Code Review: Stateful Code & Invariants

For any diff that adds a cache, memo, dedup key, or other stateful invariant, the review must answer four questions:

• Write the invariant in one sentence. Example: "cache[key] holds the close of the most recent real candle ingested for key." If the author cannot write the sentence, the cache is wrong.
• State the invalidation criterion. When does this entry become stale? What re-establishes correctness?
• What happens if the invalidator never fires? This is the failure mode that ships latent — the path through which the cache freezes at an early value and corrupts all downstream reads. Reason about it explicitly.
• Function signatures must not lie. If a function takes a parameter (e.g. getLastKnownClose(key, gapStart)) that the implementation can branch around (cache-hit ignores gapStart), the signature claims time/context sensitivity the implementation does not honor. Flag it.

Code Review: Test the Failure Mode

If a feature exists because a failure mode can occur (e.g. flat-fill exists because the exchange can return empty), that failure mode must be exercised by a test — not just the happy path it produces. Happy-path-only verification with no failure-mode probe ships the bug latent because it manufactures confidence without proving the failure path.

Prod-Touching Actions

Before recommending or executing any prod-touching operational action (SQL writes, helm changes, manual job triggers, drafting instructions for teammates), apply the pre-action-verification skill. Four gates: read the code path in-session, search the tracker for incidents against the affected component since the relevant code shipped, compute the scale delta vs the verification, and state the rollback. A "Done" Jira ticket plus a positive status report is not a substitute for re-reading the code path.