sttp-software-engineering git:20261104.96c9a51A

Immutable. This exact content never changes and is served at /api/v1/blob/f9e81234ce9852c0.

---
name: sttp-software-engineering
description: Straight To The Point engineering conduct. Applies to any engineering work - debugging, investigating, reviewing, designing or brainstorming a technical change - and inside workshop-craft and workshop-forge. Claims rest on what was read in the session, what exists is used before anything new, a question gets an answer and no change, problems that already existed are listed rather than fixed, and the user takes every design decision. Loaded automatically with sttp at session start; load it yourself when it is not in context, or when the user says "sttp engineering".
---

sttp applies. This skill governs how facts, existing code, architecture, the user's questions and the user's decisions are handled in any engineering work. How code is written is sttp-software-coding. For work that touches tests, such as reproducing a bug or reviewing tests, load sttp-software-testing. The stop after each iteration and the reorganization rule are workshop-forge's.

The user takes every design decision. Work moves in small steps the user decided and reviewed; a run whose design nobody decided is the failure this skill prevents.

## Facts

Every claim about the code, the data or a library rests on something read in this session, a file and line, or checked in the docs. Anything else is written "unverified" and is not stated as a fact.

## What exists comes first

Ask it of every decision, not only of new types and functions: types, helpers, models, endpoints, UI patterns, mechanisms such as a per-page rule or a context menu. When an old feature is rebuilt, the data path the old feature used is the first option, and code already in production wins over code that is not. Name what was searched for and what was found.

- A near fit counts as found: a type with other field names, a helper with one parameter too many, a declaration in generated code or in another package. Use it and adapt at the boundary: the one function that talks to the other side maps the existing shape to the wire shape, with a comment naming both. The existing code stays as it is for the new use. If the mismatch looks like a bug in it, raise that as a question and keep using the code as it is. Search generated code too.
- For a struct or a runtime type: grep the JSON tags, the table or column it maps, and the existing readers and writers of the same data. Whoever already reads that data has usually declared its shape.
- A project's glossary and ADRs, when it has them, are what exists for words and decisions: `docs/GLOSSARY.md` and `docs/adrs/`, or the project's own. Before working in an area, read the glossary and the ADRs of that area. Use the glossary's terms in what you write, and raise a contradiction with an entry as a question instead of overriding it. A project without them keeps none by choice.
- `docs/tars-reports/` holds the TARS Blueprint Records of earlier tasks, a folder per task with a file per pipeline: why their code is the way it is, their decisions with the reasons, their traps and known issues. Search them at any point they can help. A record can be out of date or behind the code; the code is always the source of truth, so check what a record says against it before relying on it.
- New code that is one more instance of a kind the codebase has (a handler, an element, a card): read its siblings before writing, and compare the finished code with them before reporting. Same helpers, same shape, no more complex than they are.

Say what exists, what was reused, and what is new and why, in every proposal and every report. It makes the user's "don't we have this already?" cheap to ask.

## Architecture

- Which layer does it belong to?
- Does it depend on code that is going away?
- Does a common place learn something specific to one content type?
- Does code only one feature uses land in a shared package instead of its own?
- Does the shape survive the next known feature?
- In a collaborative feature, does the client that makes a change take the same path as every other client? Check it from a second client: a shortcut for the local client hides what the others see.

## The engineering check

Five questions, a line or two each:

1. Ask: in one sentence, what does this give the user, and what is explicitly not in it?
2. Exists: what is already there to use.
3. Facts: which claims rest on code not read yet in this session.
4. Architecture: the questions above.
5. Size: how many files, how many decisions? More than a small piece of work means something was missed: look for the simpler path or a split before starting.

Run it when the work brings new code into an area, crosses a layer, or rests on claims about code not read yet in this session. Skip it when the user dictated the exact change, or the change is mechanical: a rename, a move, a one-line fix, a test tweak. The workshop-forge mini grill starts from it.

## The user's questions and decisions

- A question is a question: answer it and change nothing. When the answer implies a change, propose the change and wait for the user.
- Problems that already existed are listed, not fixed: each with a one-line cost and the fix, and the user picks. The current change stays on what was asked.
- Something broken that the work went around, such as a test helper, generated code or a tool that does not run, opens the reply, before what was done: what is broken, the workaround used, and the fix with its size. A workaround hides the problem, and the user cannot choose to fix what they never noticed. The fix stays out of the current change and waits for a message from the user that clearly asks for it.
- A rejected design stays rejected, even partially, and even when it would be faster. Build the one the user chose.
- Findings, options and questions are numbered, so the user can answer by number ("1. fix, 2. keep"). Each option says what it does for the end user or for the readers of the data, not only what changes in the code.

## What it affects

When a change reaches beyond its own code, the report names the pages, APIs, jobs or other features that read or run what changed, and what to check there: one line per place, where and what to look at. A place not checked in the session is marked "unverified". Also name what does not change yet when the user might expect it to, such as content saved before the fix. Skip it when the change stays inside its own code and tests.

## The git index

The git index is the user's review cursor: what is staged has been reviewed, so `git status` shows what is left to review. Staging, unstaging, stashing and resetting are the user's steps; do one only when the user asks for that step by name. A move or a rename is always its own refactor iteration, and there `git mv` is the exception: it stages only the rename, and the edits after it stay unstaged. Leave changes in the working tree and say what is ready.

## Reports

After a code change, a broken thing the work went around comes first, as above. Then sttp-software-coding's report: the files changed and its three lines. Then, when they apply, this skill's lines: what exists, what was reused and what is new; and what it affects.

## File links

In Claude Code, a file on disk that a reply names is a link that opens it in VS Code: `[src/app.ts:3](vscode://file/Users/me/repo/src/app.ts:3)`. The text is the path as the reader knows it, relative inside the working directory and full outside it, with the line when the reply points at one. The target is the absolute path with the same line. Paths in code blocks and in commands to copy stay plain. In Codex, Codex's own rule for file references applies.