AGENT SKILL

spec-drift

Detects drift between what is specified, documented, built and tested, and reports each mismatch with the likely truth and the side to change. Use when the user asks 'does the code still match the spec' or 'are the docs up to date'. Not for gaps inside the requirements (use requirement-gaps).

License 许可
Apache-2.0
所属仓库
quark-sri/qestack
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
spec-drift
license
Apache-2.0
description
Detects drift between what is specified, documented, built and tested, and reports each mismatch with the likely truth and the side to change. Use when the user asks 'does the code still match the spec' or 'are the docs up to date'. Not for gaps inside the requirements (use requirement-gaps).
argument-hint
[spec or contract] [code area]

03 SKILL.md 正文

spec-drift

Objective

Over time, the spec, the code, the documentation and the tests tell different stories. Each difference is a bug, a missing feature, dead code or a stale document. This skill finds the differences and says which side is probably wrong.

Context

  1. Read .agents/qa-project-context.md if it exists. Use its requirement sources and contract files.
  2. If it does not exist, search the repository for the specs, contracts and documentation. Do not stop the work for the context file.

Discovery questions

  1. Which sources are in scope: a spec, a contract, a documentation page, a code area, the tests?
  2. Which source is the approved truth when two sources differ?

Workflow

  1. Extract the claims from each source. Examples: endpoints or functions, fields and types, required and optional fields, allowed values, limits. Also error codes and messages, defaults, status transitions, side effects and permissions.
    • spec and contract: what must be
    • documentation: what users are told
    • code: what is implemented (code paths, validation, mappings)
    • tests: what is checked (the assertions, not the test names)
  2. Match the claims by a key (endpoint and field, function and parameter, requirement ID).
  3. Classify each difference: MISSING IN CODE, EXTRA IN CODE, DIFFERENT, STALE DOC, TEST ASSERTS OLD BEHAVIOR, UNTESTED CLAIM.
  4. Decide the likely truth. The newest approved spec usually wins. If you cannot tell, write "ask the owner".
  5. Rank by impact. A contract change that breaks clients is high.

Output

## Spec drift: <scope>

Claims compared: <n> | Differences: <d>

| # | Type | Key | Spec says | Code does | Docs say | Tests check | Likely truth | Impact |
|---|---|---|---|---|---|---|---|---|

Actions: code to fix / spec or docs to update / tests to fix or add / questions for the owner

Anti-patterns

  • Assuming the code is right because it runs in production.
  • Reading test names instead of assertions. A test named "rejects negative totals" may check nothing.
  • Changing sources in this skill. Report the drift; the owners decide.

Done when

  • Each claim in scope is matched across the sources, with a location for each quote.
  • Each difference has a type, a likely truth and an impact.
  • The actions are listed for code, docs, spec and tests.

Related skills

  • requirement-gaps: gaps inside the spec.
  • contract-testing: stops contract drift between services.
  • test-coverage-map: the untested claims in depth.
  • api-testing: tests for the drifted endpoints.

04 同仓库更多 Skills

quark-sri
quark-sri/qestack

unit-testing

Writes, fixes or improves unit tests for rules, calculations, validation and state logic: arrange-act-assert, exact oracles, boundary sets, doubles only at boundaries, controlled clock and randomness. Use when the user says 'write unit tests', 'TDD this' or 'mock this dependency'. Not for HTTP endpoints (use api-testing).

★ 1
quark-sri
quark-sri/qestack

ui-automation

Writes, fixes or structures browser end-to-end tests for critical journeys: role, label or test ID locators, auto-waiting assertions, API data setup, page objects, auth reuse and traces. Use when the user says 'UI test', 'end-to-end test' or 'our UI tests are brittle'. Not for business rules (use unit-testing).

★ 1
quark-sri
quark-sri/qestack

testcase-reviewer

Reviews automated tests or manual test cases like a senior test architect: scores fidelity, oracles, assertion depth, edge cases and determinism, and finds tests that pass on wrong code. Use when the user says 'review my tests', 'test smells' or 'review AI-written tests'. Not for fault injection (use mutation-probe).

★ 1
quark-sri
quark-sri/qestack

testability-review

Scores how testable a feature, module or design is before tests exist (seams for clock, randomness and network, hidden state, observability) and gives the smallest production change per blocker. Use when the user asks 'is this testable' or 'why is this hard to test'. Not for writing the tests (use unit-testing).

★ 1
quark-sri
quark-sri/qestack

test-strategy

Writes a test strategy for a product, system or team: quality goals, test levels and their share, environments, data, automation scope, non-functional testing, metrics and a roadmap. Use when the user says 'test strategy' or 'QA strategy'. Not for one sprint or release plan (use test-planning).

★ 1
quark-sri
quark-sri/qestack

test-runner

Finds how a project runs its tests, runs the right subset, and triages each failure as product bug, test defect, environment problem or flaky test, with evidence. Use when the user says 'run the tests' or asks 'which tests fail and why'. Not for pipeline design (use ci-cd-integration).

★ 1