Magnus Hedemarkandfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
c568bac43e
Issue/ticket bodies emitted from a delivery run must be written for a cold
reader: a contributor with none of the session context and no access to the
agent's local artifacts. Encode this at the change-contract layer so any run
that emits tracker artifacts inherits it.
- templates/change-contract.md: new "Issue/ticket body (cold-reader
requirement)" section listing the five requirements (background naming the
investigation, complete inline evidence with file:line refs, reproduction
commands runnable by a stranger, acceptance-criteria checkboxes, no
agent-local paths or private-artifact references), plus a header-note
pointer with the litmus test.
- references/journey.md: journey-level statement of the requirement plus
pointers at phase 1 (intake output row) and phase 5 (verification-planning
output row) where tracker artifacts are emitted.
- evals/evals.json: add case cold-reader-issue-body-gate covering a body draft
that references off-repo artifacts ("artifact pyramid", local /tmp ledger,
detail available on request) and must be rejected/rewritten by the gate.
Closes #385
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
neckbeard
An evidence-driven operating model for software delivery — not a "10x developer" persona, but a disciplined workflow that helps an AI agent choose the smallest safe intervention, prove it worked at the real delivery boundary, and leave an audit trail a human can inspect.
Why Install This Skill
Most "senior developer" prompts fail the same way: they make an agent emit short, confident code and call it effectiveness. Scott Logic's critique of the Ponytail benchmark showed that a static behavioral prompt plus a narrow, gameable metric (lines of code) cannot substantiate any real claim about software engineering. Swapping the persona for the three words "Follow YAGNI principles" nearly matched its score.
neckbeard is the answer to that failure mode. Instead of performing a character, it gives an agent a bounded, stage-aware spine: frame the change, discover the real system before designing, pick the smallest intervention that is still safe, execute by SDLC stage, record evidence, and stop or escalate when the evidence runs out. Minimalism is treated as a consequence of understanding, not a reflex — so the bundle does not win by reflexively deleting or compressing.
Install it when you want delivery discipline that is inspectable. Every non-trivial run produces an evidence ledger: intent, inspected artifacts, assumptions, rejected alternatives, files changed, checks run, observed outputs, and the boundaries that were not verified. "Done" is prohibited unless the declared verification target was actually exercised. For a test-only regression guard around already-correct production behavior, the bundle uses a bounded lightweight path with clean-baseline and targeted-mutant evidence rather than ordinary bug-fix reproduction requirements.
What You Get
| Path | What it provides |
|---|---|
SKILL.md |
Thin umbrella that routes a request through the delivery spine and composes specialist catalog skills |
references/stages.md |
Entry conditions, required evidence, exit conditions, and escalation rules for each SDLC stage |
references/lightweight-test-hardening.md |
Bounded path for test-only regression guards: baseline-pass / mutant-fail evidence, hermeticity, finality-before-push, and review pacing |
references/evidence-ledger.md |
The ledger schema and the rules for distinguishing a component check from a delivery-boundary check |
references/risk-authority-gates.md |
Stop and escalation rules; the gate before any mutation, deploy, merge, or destructive act |
references/routing-table.md |
"Use existing skill instead" table so the bundle composes the catalog rather than swallowing it |
references/journey.md |
Canonical 9-phase change-request journey — intake, discovery, design, spec, test plan, implementation, review, readiness, authorized release — with four delivery paths |
references/lifecycle.md |
Platform mechanics for GitHub (reference mode) and enterprise contexts — intake snapshots, CI/review monitoring, terminal states, and post-merge release authority |
references/delivery-packet.md |
Durable cross-phase handoff: provenance, resumability, gate verdicts, exact-head binding, lifecycle states, and an artifact ownership map |
references/position-assessment.md |
Entry mode for picking up delivery work that started elsewhere: artifact inventory, phase exit-condition scoring, a position report, and packet bootstrap |
references/tracker-discovery.md |
Intake sub-step that detects which tracking system holds the work item and routes tracker operations to the matching tooling skill (linear, jira-cli, notion) |
references/evaluation.md |
Evaluation methodology: fixtures, baselines, rubrics, multi-run reporting, claims policy |
templates/ |
Change contract, decision record, evidence ledger, verification plan, evaluation report |
templates/delivery-packet.md |
Fillable delivery packet template mirroring the nine field groups defined in the reference |
evals/evals.json |
Schema-v1 output-quality evaluation cases covering routing, gates, skip reasons, exact-head binding, terminal states, and lightweight test-hardening semantics |
eval/ |
Versioned evaluation harness: task schema, scoring rubric, baseline protocol, fixtures, and a runner |
Quick Start
Load the umbrella when a non-trivial change lands — read SKILL.md and follow
its core loop. For a bug, the agent frames a change contract, loads
systematic-debugging for root cause, makes the smallest safe fix, verifies at
the real boundary, and writes an evidence ledger. For a feature, it routes
discovery to product-discovery and specification to spec-driven-development
before writing code.
To run the evaluation suite against your harness:
python3 eval/run_eval.py --suite eval/fixtures --report out/report.md
Triggers
- Asked to fix, build, refactor, review, verify, or release software where the work is non-trivial.
- A change needs a defensible "done" backed by evidence, not a claim.
- You want an inspectable record of what was inspected, assumed, changed, and left unverified.
- You need to evaluate whether a delivery skill actually improves outcomes.
- You are delivering a change request — an issue, ticket, or tracked request — from intake through planning, gates, implementation, and review to a verified PR (or equivalent reviewable deliverable).
- You need to carry work from an issue to a PR to an authorized post-merge release with resumable, exact-head-bound state across phases.
- You are asked to continue work someone else started — a half-implemented branch or adopted spec with no delivery packet — and need an evidence-based answer to "what step are we on and what remains?"
- Your product tracks work in Linear, Jira, or Notion, and the lifecycle should operate that system through its own tooling skill instead of assuming GitHub.
Do not trigger for single factual questions, fully-specified one-line edits, or tasks already owned end-to-end by a more specific skill. The change-request journey is not loaded for a plain fix, refactor, or review that has no issue/ticket trajectory.
Requirements
- An agent harness with file read/write, terminal access, and skill loading.
- No network or runtime dependency in the bundle itself.
- The evaluation runner needs Python 3.9+ (standard library only).
- Recommended companion catalog skills (loaded on demand, not required):
product-discovery,spec-driven-development,software-architecture-analysis,systematic-debugging,technical-documentation,verification-methodology.