build

Files (1)

• SKILL.md

SKILL.md (first lines)

Read `scaffolding/scope.md`, `scaffolding/design.md`, and `scaffolding/readiness.md`. Write the actual software.

## Steps

1. Read all three scaffolding docs fully
2. Read `preferences.md` if it exists
3. Load and follow `skills/build-discipline/SKILL.md` throughout BUILD. It is the default workflow for slice sizing, test-first implementation, debugging, and change summaries.
4. If `scaffolding/readiness.md` is missing, materially out of sync with `scaffolding/scope.md` or `scaffolding/design.md`, or says the project is not ready to build, stop and run `/analyze` before writing code.
5. **Write the integration/e2e test skeleton first** — before any implementation. This is the oracle that guides all subsequent work:
   - Create the test file(s) with one test case per acceptance criterion ID (`AC-*`)
   - Each test should call the real entry point (CLI, API endpoint, function) and assert the expected outcome
   - Name test cases, fixtures, comments, or table rows with the corresponding `AC-*` identifier so traceability survives refactors
   - **For external integrations**: use the test strategy declared in design.md (mock / recorded / live). If design.md says "mock," set up fakes. If "recorded," use record-replay fixtures. If "live," tests call the real API (mark these as integration tests that can be skipped offline).
   - Tests will fail initially — that's the point. They define "done."
6. Build in **vertical slices** — get one acceptance criterion working end-to-end before moving to the next:
   a. Pick the most foundational `AC-*` from `scaffolding/readiness.md`
   b. **Before writing new code, read existing code in the project.** Match the style, patterns, naming conventions, and error handling approach already established. Consistency across vertical slices matters — especially when sessions restart and a different model instance continues the work.
   c. Keep the slice small enough to verify quickly. If it would touch more than about 5 files or you write more than about 100 lines before checking the verification ladder, split it again.
   d. Write the code for it
   e. **Verification ladder**: Does it compile? → Does the unit work? → Does the test pass?
   f. Record a brief handoff note before moving on:
   - `AC`: which `AC-*` this slice addressed
   - `Changed`: what this slice altered
   - `Not touched`: nearby code intentionally left alone
   - `Concerns`: risks, follow-ups, or scope-reduction pressure worth watching
     g. Only move to the next criterion after this one passes
     h. Repeat
7. Follow the directory structure from design.md exactly
8. **Scope lock**: Only build what's in scope.md. If you think something else is needed, note it under "## Deferred" in scope.md and move on.
9. **No silent scope reduction**: Do not satisfy an acceptance criterion with placeholder text, mocked behavior, dead-end navigation, or other shells unless scope/design explicitly says that is acceptable. If an `AC-*` cannot be completed honestly within the current plan, stop and surface the issue under `## Clarifications Needed` or `## Deferred` rather than quietly weakening the feature.

## Internal QRSPI (think, don't document)

For each vertical slice:

- **Questions**: What do I need to understand?
- **Research**: Look at APIs, docs, existing code
- **Design**: How should this piece work?
- **Structure**: What files/functions?
- **Plan**: Do it

## After all slices are built

### Create project-specific agents (house/skyscraper only)

If the quality tier is **house** or **skyscraper**, evaluate whether the architecture has clear roles that would benefit from custom agents in `.github/agents/`. Only create agents when a role is obvious from the code — don't speculate.

Each `.agent.md` file should have:

- A focused `description` with trigger phrases for discovery
- Minimal `tools` — only what the role needs
- Clear constraints on what the agent should NOT do

Common patterns:

- **Explorer**: read-only, knows module boundaries (`tools: [read, search]`)
- **Test writer**: knows test patterns, fixtures, conventions (`tools: [read, edit, search]`)
- **Reviewer**: knows acceptance criteria, audits against spec (`tools: [read, search]`)
- **Ops**: knows deploy target, runbook, rollback (`tools: [read, search, execute]`)

These agents are **project code** — they live alongside scaffolding as permanent project artifacts.

Run the **post-build gate**:

- [ ] Code compiles / typechecks (run the build, check for errors)
- [ ] Every `AC-*` from scope.md has a corresponding test and traceable proof path
- [ ] All tests pass
- [ ] No secrets/credentials in source code
- [ ] Dependency audit passes — run the appropriate command (`uvx pip-audit`, `npm audit`, `cargo audit`, etc.) and confirm no high/critical vulnerabilities
- [ ] Lockfile exists if project has dependencies (`uv.lock`, `Cargo.lock`, `package-lock.json`, etc.)
- [ ] Code follows design.md directory structure and interfaces (manual check — reconcile agent runs next for deeper audit)
- [ ] No `AC-*` is marked complete via placeholder or knowingly reduced behavior

If any gate condition fails, fix it and recheck. Up to 3 retries.

Log the result to `scaffolding/log.md`:

```markdown
## BUILD — [timestamp]

- **Gate**: PASS (attempt N)
- **Evidence**: [list each acceptance criterion with pass/fail]
- **Changes**: [files created/modified]
- **Retries**: [total gate attempts this phase]
- **Next**: REVIEW
```

Git checkpoint:

```
git add -A && git commit -m "feat(build): implement [project] core functionality" -m "[list acceptance criteria with pass/fail status]\nGate: post-build PASS (attempt N)."
```

**Auto-continue to REVIEW** unless the user specified stepped mode.

## Debugging Protocol

When a test or build fails, **diagnose before fixing**. Never blindly retry.

1. **Observe**: Capture the exact failure output.
2. **Reproduce**: Make the failure happen reliably before changing code.
3. **Localize and reduce**: Narrow the failing layer and reduce to the smallest case that still fails.
4. **Document**: State the root cause in one sentence before writing any fix.
5. **Fix**: Make the minimal change that removes that root cause.
6. **Guard**: Keep or add the regression test so the same failure cannot slip back in.
7. **Verify**: Re-run the targeted failing check, then broader verification.

If you cannot identify the root cause after 3 analysis attempts, STOP and report.

## Red Flags

- More than about 100 lines written before verification
- Multiple unrelated concerns mixed into one slice
- Tests added only after the code already appears complete
- Silent design drift or dependency changes
- "While I'm here" edits outside the current acceptance criterion

If you hit a red flag, shrink the slice and re-establish proof before continuing.

From RCSnyder/lights-out-swe-plugin, MIT.

More from RCSnyder/lights-out-swe-plugin