construct

Files (1)

• SKILL.md

SKILL.md (first lines)

# construct — build it, test-first, no spaghetti

Your job is to turn a plan (or a clear small ask) into working code that matches how this
project is already written, proven by tests you wrote *before* the code. You build in small
slices, keep each one green and committable, and stop when the task is done — not more.

Read [CONVENTIONS.md](../../CONVENTIONS.md) for the workspace (§1), the ledger (§2), reconciling against the code (§5.2), integrations and data leaving (§10), memory
(§4), role dial (§6), skip rules (§7), multi-agent rules (§8), the commit/push policy (§12),
the close-out summary (§13), freshness (§17), and workspace integrity (§20).

**Journal every run (§2.1).** The first write of the run, once the task folder is resolved
(§20.1), is a START entry in the task's `log.md`; then set this phase `in_progress` in
`state.json`. Append a DECISION entry before acting on any choice that shapes the work, and
a STOP entry before every reply that ends the turn. Write only the files the workspace tree
names (§1): nothing lost, nothing stray. Before asking a question or deciding, check the
user's judgment (§4.1) for a confirmed rule that covers it, and journal who decided.

## Step 1 — Standards & patterns: scan, then detect or establish

Before writing anything, know the rules of *this* codebase and how it already solves things.

- **Scan the related code.** Read the modules this task touches and their neighbours. Find
  the **patterns to reuse** — the existing service/repository/component shape, shared
  utilities, validation/auth/error helpers, state management, naming. Extend those instead
  of inventing a parallel approach; matching what exists beats any external "best practice."
- **Follow the neighbours' *organization*, not their *defects*.** Match how the codebase lays
  things out — folders, naming, layering, error style. Do not inherit a sibling's defects just
  because they are there: where the repo states a rule (a linter's length/complexity limit,
  a documented convention) the new code meets it even when neighbouring code doesn't, and you
  note the neighbour's violation rather than copying it. That covers a **stated-rule gap**
  only: a neighbour that is actually defective (unsafe, or wrong in what it returns) is §4.2's
  stop, with its evidence and the user's fix-here-or-isolate choice, never a quiet note.
- **Follow the code, name what you followed, and ask when it has two ways (§4.2).** Before
  writing code of a kind the repo already has, mirror its nearest existing instance and
  record `Mirrors: <path> (<what>)` in the journal and the change summary. If instances of
  that kind disagree, stop and ask, with the evidence and a recommendation §4.2 lays out:
  never pick one silently, never blend them, never add a third. A plan task whose `Shape`
  already names the way settles it.
- **Seen a better way? Propose it, never slip it in (§4.3).** A newer API, a faster query, a
  responsibility in the wrong place: if it clears §4.3's bar (a named gain, evidence,
  bounded, near the work), put it to the user with options and your pick, in the same round
  as any other question, and build what they choose. If it does not clear the bar, it is not
  raised.
- **Existing code?** Detect the conventions and follow them — do not impose your own: the
  linter/formatter config, the test framework and how tests are named and laid out, folder
  structure, error-handling style. Record what you found in `standards.md` so later tasks
  and workers stay consistent.
- **Greenfield / no conventions?** Establish them: propose a minimal set (language idioms,
  test framework, structure, formatting) and get a quick approval, then write them to
  `standards.md`. From then on, follow them.

Also load the **discipline pack** for the detected stack (backend / frontend / mobile /
AI-ML / any-language) from `references/disciplines/` — it adds the concerns specific to that
surface (e.g. accessibility for frontend, platform HIG for mobile, contracts for backend).

**Choosing or upgrading a tool/library/version?** Don't pick "the latest" from memory —
establish today's date and check the web for the current version and any deprecations, then
cite it (§17). A dependency the plan does not name is **never adopted on your own**: it is an
amendment (a kind the repo has never had, §4.2), put to the user with what it is for, the
evidence that it is worth taking (license compatibility, maintenance health, supply-chain
trust), and any data it sends outside (§10). Match what the repo already uses unless the task
is explicitly an upgrade.
Also load any **cross-cutting concern pack** the change touches: `database.md` (migrations,
queries), `security.md` (untrusted input/auth/secrets), `devops.md` (CI/containers/deploy).
Build the way this codebase already builds: `standards.md`'s `Stack:` and `Conventions:`
(§4) record what was detected — language, framework, naming, structure, error handling — and
they are the answer to "how is this normally written here", not your own habits. Read them
before the first line; a pattern they do not cover is one to take from the sibling files
(§17), and worth adding once you have.

Name things in the project's own words: `standards.md`'s `Domain terms:` (§4) is the
vocabulary the spec and plan already use, so an identifier that renames a recorded term makes
the code read as a different subject than the artifacts describing it. A term the build needs
and the glossary lacks gets added there, not invented in a file.

For a **frontend or mobile** task, also read `design.md` (§6.2) — the UI source of truth —
and `references/disciplines/ui-craft.md` for the universal UI craft rules (tokens, spacing,
type, states, motion, a11y, i18n). Build the screens, states, and interactions to match, and
scope depth to the build ambition (MVP vs full) from the spec.

## Step 2 — Build each task test-first (the core loop)

Work the plan's tasks in order (a trivial change is one implicit task). **Before each task,
read the locked decisions that apply to it (§5.2)**: intake `Locks:`, chosen proposal
options, the plan's `Shape` and `Mirrors`. They are the instruction. If the build needs to
differ from one, stop and raise an amendment; never switch quietly. **Build into the
files the task's `Shape:` field names, and take the structural choice it records** — that
decision passed the plan gate; changing it mid-build means the plan was wrong, which is the
amendment loop, not a silent call. For each task, run
the RED → GREEN → REFACTOR loop.

**The iron law: no production code without a failing test first.** If you wrote the code
before the test, delete it and rebuild from the test — do not keep it as a reference, do not
"adapt" it while writing the test. Code you are looking at while writing its test makes the
test describe what you wrote, not what the task needs. Violating the letter of this rule is
violating its spirit.

**These thoughts mean stop — you are rationalizing:**

| The thought | The reality |
|---|---|
| "It's too simple to need a test first" | Simple code is where the cheap test lives. Write it. |
| "I'll add the test right after" | Then the test is shaped by the code, and proves nothing. |
| "The test would just mirror the implementation" | That means you don't know the behavior yet — that's the point of RED. |
| "I already know it works" | Then RED costs seconds and confirms it. If it doesn't fail, the test is wrong. |
| "Just this once, we're in a hurry" | The exceptions are throwaway prototypes and generated code — and you ask first (§7). |

```
RED     Write ONE test for the task's acceptance criterion. Run it. Watch it FAIL —
        and confirm it fails for the RIGHT reason (the behavior is missing, not a typo
        in the test). A test that passes before you write code is usually testing
        nothing — fix it or delete it. The one honest exception is a **guard test**
        asserting that a VALID input is still accepted: it passes trivially while no
        rule exists, and starts earning its place the moment the rule lands, by
        catching a rule that is too strict. Keep those, and say which they are.
GREEN   Write the SMALLEST code that makes that test pass. No extra features, no
        speculative abstraction. Run the test — watch it pass.
REFACTOR Clean up what you just wrote while the test stays green: clear names, no
        duplication, no dead code. Update the doc-comment on any class/service/method you

From saleh-alhaddad/itqan-engineering, MIT.

More from saleh-alhaddad/itqan-engineering