Skip to main content
Spec 1.0: This example uses the current stable portable core release.
Use this when a project already has code, tests, and docs, but intent is unclear.

​
Goal

Establish current truth for one critical part of the system without trying to rewrite the whole repo.

​
Start with current behavior

In a brownfield repo, the first spec should describe what the system actually does now. Do not start with the ideal future design. That creates confusion fast, especially when the code, tests, and docs already disagree.

​
High-level walkthrough

  1. Pick one critical area first, not the whole repo.
  2. If you are entering an existing repo or branch, get context first. In specled_ex, that is mix spec.prime --base HEAD.
  3. Read the current code, tests, and docs together.
  4. Write a subject spec that matches shipped behavior and known constraints.
  5. Point verification at the evidence that already exists.
  6. Use the guided reconcile step for your stack to see whether the current change lands in covered territory or on the uncovered frontier. In specled_ex, that is mix spec.next.
  7. Run the local coverage summary to surface missing coverage and weak spots. In specled_ex, that is mix spec.status.
  8. Tighten one gap at a time.

​
Prompt you can give an agent

Treat this as a brownfield retrofit.

If you are entering an existing repo or branch, start with the session-start context command for that stack.
Read the current code, tests, and docs for one critical area.
Write one current-truth subject spec that matches shipped behavior.
Do not invent a better future design.
Tie the subject to the smallest real verification path you can find.
Use the guided reconcile step to keep the next gap small and visible.

​
What a good first slice looks like

  • one module with unclear behavior
  • one workflow that crosses several files
  • one package surface that agents tend to change
  • one area where docs and tests already drift

​
What to verify first

  • every requirement should have at least one verification path
  • every important scenario should map to current evidence
  • current docs should not contradict the new current-truth spec
One good first example is a module that already has tests but still causes repeated confusion in code review.

​
Avoid

  • trying to specify the whole repo in one pass
  • writing aspirational behavior that has not shipped
  • changing runtime behavior before the baseline is clear
  • treating every uncovered file as equally important

​
Good outcome

You know the brownfield adoption is working when:
  • the first subject matches real behavior
  • the repo can prove at least some of that behavior
  • the next gaps are visible instead of hidden
  • the team can deepen the coverage gradually without stopping delivery