momentic-spec

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: momentic-spec
description: Improve code correctness using Momentic specs in the feature development process
---

# Momentic spec-driven development

Write the expected product behavior as Momentic tests before implementing it.
The tests define the contract; do not make the tests fit the implementation.

## Non-negotiable sequence

1. Read repository guidance, `momentic.config.yaml`, and nearby tests and
   modules.
2. Identify and report the exact Momentic tests expected to be affected.
3. Create or modify those tests before changing product code.
4. Review the test diff as a product specification.
5. Only then implement the product change.
6. Use fast code-level checks while implementing; do not run Momentic after
   every edit or commit.
7. At a durable end-to-end checkpoint, prepare the required test state, enable
   the affected tests that should now pass, and ask whether to run the smallest
   affected set.

Do not begin product implementation until the intended test specifications are
on disk. If the user changes the requirement, update the spec first again.

## Choose the affected tests

- If the user names specific existing tests, start with those tests and keep the
  work focused on them. Expand the set only when repository evidence shows
  another test or shared module is directly affected.
- For new user-visible functionality, create the smallest new test or tests that
  describe the new user journey.
- For changed functionality, update the existing tests that describe the old
  behavior instead of adding duplicate coverage.
- Trace shared components and modules far enough to find real behavioral impact.
  Do not infer the affected set from filenames alone.
- If no Momentic test is affected, state why before making product changes. Do
  not make cosmetic test edits merely to produce a test diff.

Before editing product code, report each affected test path and whether it will
be added, changed, or left unchanged.

## Write the product specification first

The pre-implementation test should describe the requested outcome, even when the
current product cannot satisfy it yet.

- Preserve unrelated setup, teardown, data, assertions, and test intent.
- Do not weaken an assertion or preserve old behavior just because that matches
  the current implementation.
- Mark a test `disabled: true` when the implementation or a required dependency
  is not ready and the test is not expected to pass yet. Record why it is
  disabled and what must become true before enabling it.
- Do not use `disabled: true` merely because local credentials or a runnable
  environment are unavailable. That is a validation limitation, not necessarily
  an expected product failure.
- Keep the delta narrow. One changed product contract should normally have one
  focused test delta.

After writing the tests, summarize the expected failing or disabled behavior and
confirm the tests express the user's request before implementing it.

## Follow the codebase's testing language

Read nearby tests and follow their established conventions, including folder
placement, naming, modules, setup, data, and preference for AI checks, page
checks, or element checks. Apply baseline Momentic practices where the codebase
does not express a preference:

- Prefer native Momentic steps and natural-language targets over JavaScript or
  selectors.
- Keep assertions minimal and user-driven, with an explicit outcome check after
  a flexible action.
- Reuse existing modules for established flows such as authentication, setup,
  and navigation instead of recreating those flows inline.
- Do not reorganize or modify a shared module unless the requested product
  contract requires it. Account for every test that consumes a changed module.
- Never work around a real product failure by changing the test.

## Prefer AI action V3 for new specifications

For a new test, prefer an AI action V3 `act:` step when a high-level goal reads
more clearly as a product specification, especial