Levyra Real Engineering

Levyra real-engineering workflow

This skill adapts Matt Pocock's mattpocock/skills engineering workflow to Levyra. It is a routing layer, not a second project contract.

Precedence

Always follow, in order:

1. root and nearest AGENTS.md files;
2. owner-approved requirements and active planning;
3. matching levyra-* domain skills;
4. current implementation, tests, architecture, and workflows;
5. Matt Pocock engineering skills when installed.

If an external skill conflicts with Levyra, Levyra wins. Never create a second source of truth, a parallel cache/store/controller, or extra architecture merely because an external skill suggests one.

Choose the lightest useful lane

Do not run the full pipeline for a typo, one-line build fix, obvious null check, narrow documentation correction, or another change whose behavior and scope are already unambiguous. For those, use the normal Levyra work method and focused validation.

For non-trivial work:

0. Evidence and reuse before invention

Before adding a new abstraction, helper, dependency, workflow, cache, store, controller, parser, or architectural layer:

• search Levyra first for the existing owner, working pattern, nearby implementation, or reusable primitive;
• compare the broken/new path with at least one working local path when one exists;
• when behavior depends on a versioned external API, library, plugin, or platform rule, verify current primary documentation instead of trusting remembered behavior;
• prefer adapting a proven local implementation over importing a generic framework pattern;
• treat third-party repositories and skill catalogs as evidence and inspiration, never as authority over Levyra's codebase;
• add a dependency only when the existing stack cannot reasonably satisfy the requirement and the maintenance, security, binary-size, and compatibility cost is justified.

Do not turn this into mandatory broad web research for trivial work. The goal is to prevent needless reinvention and stale assumptions, not to add ceremony.

1. Ambiguous product or architecture: grill-with-docs

Use when requested behavior, trade-offs, ownership, compatibility, or user-visible outcome is genuinely unclear.

• Inspect the repository first and answer codebase questions from evidence instead of asking the owner.
• Ask only decisions that cannot be resolved from the repository.
• Maintain shared vocabulary only when genuinely reusable.
• Record an ADR only for a durable architectural decision with a real trade-off and meaningful reversal cost.
• Stop once the implementation contract is clear.

2. Large unknown problem: wayfinder

Use before spec work when several product/architecture decisions remain unresolved. Resolve the decision map before writing a spec.

3. Settled intent: to-spec

A Levyra spec states desired behavior/non-goals, preserved behavior, architecture ownership/reuse, relevant security/lifecycle/persistence/concurrency/localization/compatibility implications, acceptance criteria, and focused/manual validation.

Do not invent requirements that the owner did not approve.

4. Work too large for one reviewable change: to-tickets

Split into independently reviewable vertical slices. Each ticket carries scope, preserved behavior, dependencies, acceptance criteria, relevant owners/files, and validation. Publishing GitHub issues still requires explicit owner authorization.

5. Implementation: implement + tdd

Implement one ticket or one reviewable phase at a time.

• Start from a fresh context for a new independent ticket when practical.
• Read applicable Levyra domain skills before editing.
• For defects, establish a concrete failing path first; use diagnosing-bugs when root cause is unclear.
• Prefer red -> green -> refactor where deterministic tests are useful.
• Test externally observable behavior and durable contracts rather than incidental implementation details when possible.
• Do not force artificial tests around trivial declarative changes.
• Make the smallest coherent change and avoid unrelated cleanup.

Hypothesis-driven debugging

Use this closed loop:

reproduce -> isolate -> hypothesis -> smallest experiment -> fix -> prevent

1. Reproduce/capture the failing path and complete relevant evidence.
2. Trace the bad state/value backward to the first failed assumption or contract.
3. Compare with a nearby working path when available.
4. State one concrete root-cause hypothesis and supporting evidence.
5. Test it with the smallest experiment/change; do not stack several speculative changes into one experiment.
6. If it fails, revert/discard the speculative change, mark the hypothesis DISPROVED, and stop using it downstream.
7. Once supported, add the smallest deterministic regression evidence, apply the root-cause fix, and rerun relevant broader checks.
8. Prevent recurrence with the narrowest useful test, invariant, validator, or ownership clarification; do not create generic infrastructure for a one-off mistake.

Keep the current hypothesis state explicit when the investigation is long: CANDIDATE, SUPPORTED, VALIDATED, or DISPROVED. If later evidence invalidates a previously supported conclusion, retract it explicitly rather than silently leaving old reasoning in handoffs, comments, or review summaries.

After three materially different failed hypotheses, reassess the ownership boundary and reproduction evidence instead of stacking more guesses.

Test and check failure classification

Before reacting to a failed test/build/lint/runtime check, classify the failure using the best available evidence:

• PRODUCT_REGRESSION: the implementation violates the expected behavior;
• TEST_DEFECT: the test/fixture/assertion is stale or incorrect;
• ENVIRONMENT: tooling, network, service, device, permission, or CI infrastructure prevented a valid result;
• FLAKY: the same code/input/environment can legitimately produce intermittent pass/fail behavior and there is evidence of nondeterminism;
• UNKNOWN: evidence is insufficient to classify yet.

Do not rerun an unchanged failing command repeatedly to fish for a green result. A retry is evidence only when it tests an environment/flakiness hypothesis; preserve the original failure and compare both runs. Never relabel a failure as flaky merely because a retry passed once.