engineering-workflow

Files (2)

• AGENTS.md
• SKILL.md

SKILL.md (first lines)

# Production engineering workflow

Tool execution contract: use exact paths from current workspace observations, including hyphens
and underscores. When a planned file is missing, list its containing directory and reconcile the
plan with the actual files instead of guessing neighboring names. Use a current read or a hash-verified retained observation before editing an existing target.
A role change, retry or compaction does not by itself invalidate unchanged source facts.
Structured program/argv commands have no shell expansion: wildcards, pipes and redirects are
literal arguments. Discover exact dependency paths before searching them. Use an ordinary scoped
script for compound work rather than unsupported shell command-string flags. Poll interactive
handles before sending input, use newline delimiters for line protocols, and inspect completed
results instead of writing to a dead handle. Use command_output for exact retained output pages;
never repeat an effect just to obtain output. Git metadata is not a task deliverable, and a plain
folder does not imply a Git repository. These rules do not expand tool permissions.

Follow this workflow for every coding run, scaled to the requested change without dropping any
requested behavior.

1. Complete one startup grounding check per run/workspace, then get to work. Reuse that completed
   check through role changes, retries, and compaction. Read a specific target or contract when the
   next implementation or review decision needs it; do not inventory the whole repository first.
   When the authoritative request declares an input to be a black-box or opaque interface, or says
   that behavior may be observed only through a named callable, command, protocol, or API, that
   contract narrows inspection. List the input as workspace metadata but do not read or search its
   implementation, inspect private attributes, recover hidden values through reflection, or use
   those values to tune or validate the candidate. Ground the work through the permitted public
   interface, its declared contract, and independently chosen queries or metamorphic properties.
   Independent review must treat any implementation or hidden-state observation in the retained
   tool trace as acceptance-blocking contamination even when the final artifact later uses only the
   public interface.
   When the request requires opening, calling, or otherwise exercising a named URL, service,
   endpoint, command, or other public interface, use that interface and retain its direct result as
   evidence. Reading its backing source, configuration, cache, or database may support the work but
   cannot substitute for the requested interaction or prove the interface works. Independent review
   must block acceptance when the requested interface was never exercised.
   In a staged workflow whose current request names the exact input files to use, do not open
   adjacent unrequested inputs merely because directory discovery exposes them; they may belong to
   a later round. Read newly introduced inputs when the request introduces them, then reconcile
   them with the retained artifacts from earlier rounds.
2. Translate the request into a literal requirement ledger and a repository-grounded design. Keep
   every explicit path, field, value, operation, and scope phrase. Apply exclusions only to the noun
   or operation they grammatically modify; do not broaden them to unrelated aggregates. When two
   statements initially appear inconsistent, first use the narrowest ordinary reading that honors
   both. Never replace an explicit expected value with a derived value merely because a different
   interpretation looks cleaner. If no reading can satisfy both, report the actual contradiction
   instead of silently choosing a new contract. Reporting a source inconsistency does not mean
   withholding requested work that is still meaningfully constructible. When authoritative inputs
   contain one grammatically ambiguous compound rule, `narrowest` is not permission to attach a
   trailing modifier to every earlier list item or to replace another reasonable ordinary reading.
   Preserve a candidate that satisfies a reasonable reading unless another authoritative source or
   deterministic gate resolves the scope. Record the unresolved ambiguity as advisory; a blocking
   finding must show that the candidate violates every reasonable reading, not merely that the
   reviewer prefers a different parse. Do not settle whether a trailing modifier distributes over
   coordinated list items by first assuming that distribution and then citing an earlier item's
   lack of the modifier's property; that is circular. Independently consider both distributive and
   nearest-item grammatical attachments before claiming that every reasonable reading fails.
   When authoritative inputs require a closed canonical vocabulary, canonical identifiers are opaque contract values. Choose
   the registered value whose declared category and governing rule fit, keep factual
   evidence fields accurate, and report awkward naming without inventing a replacement identifier.
   Treat exact syntax as a cross-artifact contract: quoted values, stable identifiers, enum-like
   values, field names, filenames, paths, and commands must remain byte-for-byte unchanged in every
   output that records them. Human-readable prose may explain those values alongside the literal,
   but must not replace them by changing case, whitespace, punctuation, or separators.
   When a requirement says an output must mention, discuss, or reference a named artifact,
   identifier, field, clause, command, or path, reproduce that literal at least once in the owning
   output. Human-readable prose may accompany the literal but cannot replace its traceability.
   For quantitative or scientific work, establish every input and output unit, coordinate system,
   and required transformation from the supplied evidence and the named domain before calculating
   or fitting. Validate the final parameters in the requested physical domain; a numerically good
   fit in raw coordinates is not correct when the request names a transformed coordinate. Retain a
   unit ledger in tool or command evidence that names the input unit, output unit, applied formula
   or transformation, and at least one dimensional or expected-range check on the final values.
   Independent review must block when that evidence is absent or still describes raw coordinates.
   When one scalar output refers to records drawn from heterogeneous source categories, preserve a
   typed identity rather than emitting a bare record ID. Unless an exact representation is declared,
   combine the authoritative category or type label and stable ID as `category:id`; this keeps the
   reference interpretable outside its source table. Aggregate fields such as cause counts
   group by the semantic category they name, while row-level outputs retain the typed record identity.
   When producing a change log, diff, revision summary, or replan report, explicitly account for
   every constraint introduced by the triggering update. Record changed, added, removed, and
   already-satisfied constraints with their literal values so readers can distinguish deliberate
   preservation from an overlooked requirement.
   When a rule applies to named categories, require an authoritative label, taxonomy, or definition
   for category membership. Do not expand a named category to a related concept merely because the
   domain association seems plausible; preserve the literal category boundary when the source does
   not define a broader membership rule.
   Treat separately named output fields and categories as separate predicates. Unless the source
   explicitly requires overlap, do not place one item in multiple category fields merely because a
   broader prose label could describe it; derive membership independently from each field's stated
   rule and keep dedicated exception categories from leaking into one another.
   When a detail ledger is named for one member of a closed classification, treat it as a projection
   of that class only. Do not copy neighboring review, pending, informational, or other nonmatching
   classes into the ledger unless the contract explicitly declares overlapping membership.
   For reconciliation tables, exception ledgers, and their summaries, preserve explicit routing and
   material state. A requested synthetic or exception row is the item's primary representation and
   does not also belong in a reject ledger unless the contract explicitly requires both. Reject rows
   are for items that cannot enter the primary representation under its rules. Use the most specific
   evidence-supported reason. A reference lookup with no matching source record is a missing-reference
   condition, not a generic invalid-reference condition; reserve `invalid` for a present record that
   fails validation. Do not flatten a material condition such as a refund, partial match, or exception
   into a generic success status. Summary unresolved or exception counts must reconcile the union of unresolved
   primary rows and rejected items across all requested artifacts, with explicit identity deduplication, rather than counting only rows visible in one output.
   For time-window state, exclude ignored or out-of-window IDs from the accepted/seen set. A duplicate list may repeat a retained first-seen ID because it records a later observation.
   Make every partial or checkpoint result self-contained for its captured round: record completed
   identities and results, the pending or failed stop boundary, and the stop reason when they exist.
   Later rounds preserve that snapshot unless revision is explicit; mutable state and logs do not
   substitute for the snapshot's own temporal boundary.
   Treat an explicit past-time (`as of` or `at <time>`), historical-date, version, or revision
   qualifier as a source-state boundary. Prove the state at that boundary with a contemporaneous
   snapshot, source revision, or archived record. A current mutable source filtered by an item's
   release, creation, or effective date does not prove that the source had the same values, ranking,
   membership, or calculations at that earlier time; later backfills and recomputation remain
   possible. If no dated state can be recovered, report the evidence gap instead of presenting
   current state as historical fact.
   When that historical state lives in a remote repository or data collection, inspect its
   immutable manifest, index, or tree and the relevant object sizes before transferring bulk
   history or a whole archive. Prefer targeted reads from the pinned state. Client-side sparse
   patterns do not by themselves prove that the initial object transfer is bounded. After one bulk
   acquisition times out or fails for size, do not retry the same collection through clone,
   archive, or fetch variants unless new size or progress evidence shows the next operation fits;

From Corvidae-Coding-Projects/Project-Peritus, MIT.

More from Corvidae-Coding-Projects/Project-Peritus