traxxall-spec-author

When to invoke

Invoke after a successful intake brief (from traxxall-workitem-intake) when:

• requires_specification is false in the intake result.
• The user asks to "write the spec", "author the spec", "write acceptance criteria", or "spec this out".

Never invoke when requires_specification is true. The intake skill will have listed what is missing; prompt the user to update the WI first.

---

Step 1: Load standards and intake brief

Read skills/traxxall-standards/SKILL.md for dual-framework rules and test boundary.

Use the intake brief from traxxall-workitem-intake as your sole factual source. Do not fetch the WI again unless the brief is absent from context. Do not fabricate information the brief does not contain.

---

Step 2: Detect framework path

From the intake brief's affected_projects and framework_path:

• Legacy (Traxxall.Web, Traxxall.Admin, Traxxall.WebApp, Traxxall.WebApi): note that dependencies use ServiceLocator.Current.GetInstance<T>() and EF6. Do not mention constructor DI.
• Modern (Traxxall.NETCore.WebApi, Traxxall.v2.UniversalAPI, Traxxall.Core.OAuth): note constructor DI. Do not mention ServiceLocator.
• Shared (Traxxall.Core, Traxxall.Models, Traxxall.v2.Infrastructure*): flag high blast-radius. Both API surfaces are affected. Enumerate which legacy and which modern projects consume the shared component being changed.

State the framework path at the top of the spec. Do not mix patterns from both worlds.

---

Step 3: Write the implementation spec

Structure:

## Implementation Spec — WI #{WI#}: {Title}

### Framework Path
{Legacy .NET Framework 4.x | Modern .NET Core | Shared core — HIGH BLAST-RADIUS}
{One sentence on the affected projects and their DI/data-access pattern}

### What is changing
{2–4 sentences describing the change in terms of system behaviour — what the system will do differently after this change. No class names, no method signatures.}

### Affected components
{List each project and — if derivable from the comprehension doc — the approximate area within it (e.g., "Traxxall.Admin — admin portal grid pages", "Traxxall.Core — shared query layer")}

### Implementation approach
{Step-by-step approach grounded in the relevant comprehension doc. Reference the comprehension doc path explicitly. Each step describes what to do, not how to write the code. Use the correct DI/data-access pattern for the detected framework. Maximum 10 steps.}

### Data and schema considerations
{Any database query, table, or schema impact. For schema changes, reference docs/comprehension/how-to/apply-a-database-schema-change.md and note that migrations are ad-hoc SQL, not EF migrations (ADR-0003).}

### Blast-radius note (shared core only)
{When touching Traxxall.Core, Traxxall.Models, or Traxxall.v2.Infrastructure* — list all consuming projects and the regression risk.}

---

Step 4: Write acceptance criteria

Critical rule: acceptance criteria must be written so a blind QA agent — one that has never seen this spec, cannot read the codebase, and derives its Playwright test from the AC text alone — can construct a valid automated test.

This means:

• Name the observable behaviour (what the user sees or what the API returns).
• Name the input conditions (which screen, which data, which user role, which trigger action).
• Name the expected outcome (the exact observable result — a displayed value, a persisted record, an error message, a redirect).
• Do NOT name any class, method, interface, or internal implementation concept.
• Do NOT say "the service validates" or "the repository saves" — say "the system displays" or "the record appears in the list".

AC format

Use Given/When/Then format:

## Acceptance Criteria

### AC-1: {Short title of the scenario}
**Given** {the starting state or precondition — name the screen, user role, and data}
**When** {the user action or system event that triggers the behaviour}
**Then** {the observable outcome — what the user sees, what the API returns, or what appears in the data}

### AC-2: {Error or edge case scenario}
...

Minimum two AC entries: one happy-path, one error or edge case. Add more as needed to cover all product-level requirements stated in the WI description and intake brief.

AC anti-patterns to avoid

Do not write	Write instead
"the ComplianceService validates the record"	"the system displays a validation error on the compliance form"
"the MainDataContext query returns rows"	"the grid shows the updated rows after save"
"the ServiceLocator resolves the dependency"	"the feature loads without error"
"the TransactionScope commits"	"the record appears in the admin list after refresh"

---

Step 5: Write the dev-test outline

The dev-test outline is for author-side unit and regression tests only. It is not QA content.

## Dev-Test Outline

### Test project
UnitTests.Core (or the appropriate author-side test project for the affected module)

### Pattern
TransactionScope rollback — every database operation is wrapped in a TransactionScope that is not committed, so no persistent state is left after any test run.

### Test stubs

#### Test 1: {happy-path scenario name}
- Arrange: {what state to set up — in terms of test data, not mocks of specific classes}
- Act: {what operation to invoke — describe the user action or system call in plain language}
- Assert: {what to verify — the observable result, not internal state}
- Rollback: TransactionScope.Dispose() (never call Complete())

#### Test 2: {error or edge case}
...

### Do not run
These stubs must not be run in CI without explicit manual review. Do not invoke the destructive utility projects (cache manipulation, mock data population). These test stubs target UnitTests.Core only.

---

Guardrails

• Never include class names, method signatures, or namespace paths in acceptance criteria.
• Never fabricate spec content — if the intake brief does not contain enough information, state what is missing and decline to spec.
• Never produce QA Playwright tests or blind-adversarial test content.
• Never reference the wrong DI pattern for the detected framework (no ServiceLocator in modern path; no constructor DI in legacy path).
• For shared-core changes, always enumerate the consumer projects and flag blast-radius.

---

Output envelope (result shape)

The result field for pbi_draft or intake-to-spec flow:

{
  "wi_number": 16472,
  "framework_path": "legacy|modern|shared",
  "blast_radius": false,
  "blast_radius_consumers": [],
  "ac_count": 3,
  "ac_titles": ["AC-1: Grid shows updated rows", "AC-2: Validation error on empty field", "AC-3: No change on cancel"],
  "dev_test_count": 2,
  "comprehension_doc_used": "docs/comprehension/how-to/add-a-web-forms-page.md"
}