Architect Calculator

Architectural calculator - constants-first sizing pipeline

The calculator is the most responsible artifact of the project: its numbers drive hardware and cost decisions. The math is NEVER invented in the workbook. It is built bottom-up through five stages; each stage gates the next.

Pipeline (user orders 2026-08-25: mini-ERIR sizing session; understand-then-lock first)

0. SYSTEM UNDERSTANDING - first understand the system the calculator is made for. The agent states its model of the dataflow and layers (who writes what, in what order) and the user corrects it. A wrong mental model invalidates every downstream number - the user's correction here is the most valuable input of the whole pipeline. No artifacts.
1. MANDATORY INPUTS LOCK - strictly fix the data without which nothing can be computed: the base inputs every number traces to (inflow per period, volumes per store, retention, ratios). Locked with the user; a missing mandatory input blocks all calculation - it is a question, never a filled-in guess.
2. CONSTANTS FILE - the single source of truth. A python file holding constants only:
   • ONLY constants. No explanatory comments, no essay text, no argumentation - only group header comments (# TIME, # PRODUCTION DATA, # RATIOS). Argumentation lives in chat and in the justification stage.
   • No magic numbers: every literal is a named constant (0.60 -> S3_FILE_SHARE_OF_INCOME, 6 -> S3_WINDOW_MONTHS). A number appears only as the value of a named constant.
   • Measured per-entity data goes in dicts (hashmaps); totals and ratios are COMPUTED from them, never re-typed.
   • User's exact variable names are honored. Python forbids identifiers starting with a digit (12MONTH -> MONTH12) - state that to the user, do not silently rename.
   • Derived constants reference their sources and are defined after their dependencies.
   • Dead constants (unreferenced, superseded, None placeholders) are removed.
3. RESEARCH - fill UNKNOWN constants. Sources: measurements from prod (SQL over partitions, MinIO listing, counters), official vendor docs for ratio norms. Every constant gets a status argued in chat: measured / user-given / derived / assumption.
4. CONSTANTS RECURSION - research results update the constants file; new gaps surface; loop until every constant that matters has a value. Two or three passes is the normal state, not a failure. This is where the pipeline spends most of its time.
5. JUSTIFICATION - human-readable text (Telegram message, doc) drawn FROM the constants: every number in the text traces to a named constant. The user owns the wording; the agent proposes phrasing, the user edits the file. The agent NEVER full-rewrites a user-edited file - targeted edits only, re-read first.
6. XLSX RENDER - only when every variable is known and the math is locked (stage 5 done). The workbook RENDERS the locked computation; it adds no math of its own.

HARD GATE - the workbook

• Not started until stage 4 is done and the user has named the desired final cells.
• ALL math is prototyped as a throwaway python script in /tmp and cross-checked by a second, independent computation before any xlsx exists.
• xlsx formulas carry the locked constants' values; no magic numbers in formulas.
• Delivery gate: check.py AND check_usage.py AND unwind.py all pass, and the justification text's numbers match the constants (extract-and-compare).
• Nothing beyond the user's named blocks: no helper cells, no decorative text, no own constants block inside the workbook.

HARD rules (from the mini-ERIR session)

• Units: binary (TiB = 2^40) and decimal (TB = 10^12) are different scales - name the scale in the variable name or state it. A TiB/TB mix is a ~10% error that survives every check because it is consistent.
• Replication and erasure coding are explicit named multipliers, applied per system according to its architecture:
  • Kafka: replication factor multiplies disk (each segment stored N times).
  • MinIO: erasure coding multiplies physical disk; the ratio is measured from the prod topology and does NOT transfer to a different topology.
  • ClickHouse replicas SERVE queries: disk, RAM and CPU all multiply by replica count.
  • Greenplum mirrors do NOT serve queries: disk multiplies, CPU and RAM do not.
• A number in a variable cell is measured, user-given, or derived from those - never an invented "realistic" value. An assumption enters only with the user's ok and is flagged in the justification text.
• The user edits artifacts themselves; agent edits are targeted (edit), never a full-file rewrite of a file the user touched.
• Vocabulary is locked by the user's accepted terms; introducing a synonym (e.g. "зеркала" instead of the user's "репликация") is a defect.

Scripts

Absolute paths (all relative to this sub-skill's directory calculator/):

Failure modes

Current state

Session mistakes

• 2026-08-25: presented a dataflow with wrong layer shares (treated ФХ as the source of everything, ignored the highload -> Kafka -> ФХ -> ETL -> ODS Cloudberry -> DS -> CH chain); the user corrected it ("ты не понимаешь архитектуру"). Prevention: stage 0 - state the dataflow model first and get the user's correction before any percentage.
• 2026-08-25: full-file rewrite of message.txt clobbered the user's cleanup (Kafka/MinIO lines); he had to re-fix. Prevention: targeted edits only on user-edited files.
• 2026-08-25: formal-language pass changed word order and register beyond the asked orthography ("Пускай"->"Пусть", "прод"->"продакшена", "софт"->"ПО"); user reverted. Prevention: fix exactly what was asked, list the rest as options.
• 2026-08-25: introduced "зеркала" where the user's term is "репликация". Prevention: lock vocabulary from the user's accepted terms.
• 2026-08-25: constants referenced before definition; an eval kernel cached a stale module. Prevention: define dependencies first; verify with a fresh python process.
• 2026-08-25: Cloudberry segments initially computed from the mirrored disk, doubling CPU/RAM wrongly; mirrors do not serve queries. Prevention: replication semantics per system before writing formulas.