papi-sdlc-task-fulfilment-audit

Files (2)

• SKILL.md
• fulfilment-audit-task-template.md · assets/

SKILL.md (first lines)

# SDLC Task - Fulfilment Audit

## Purpose

A fulfilment audit checks alignment between **user stories** and the
**capabilities** declared in component specifications, in both
directions.

It is the middle rung of the PAPI audit ladder:

| Audit | Compares | Forward | Backward |
|-------|----------|---------|----------|
| Charter | charter ↔ stories | charter → stories | stories → charter |
| **Fulfilment** | **stories ↔ capabilities** | **story → capability** | **capability → story** |
| Compliance | capabilities ↔ code | spec → code | code → spec |

The fulfilment audit asks two questions:

1. For every user story, does at least one user-facing capability cite
   it, and do the citing capabilities together cover what the story
   needs?
2. For every user-facing capability in scope, are the stories it cites
   real and correctly attributed — or is the capability an orphan?

The output is a findings list with a disposition for each finding:
update the stories, update the component specs, or accept-with-note.

**This needs the PAPI long task skill.**

## This audit examines; it does not execute

This audit *examines* artefacts (user stories, component
specifications, the capability links between them). It does NOT
execute tests, demos, or run the system. Whether stories can be
performed end-to-end through the real interface is a separate
question handled by the `papi-sdlc-task-acceptance-test` skill — not
this audit.

## Two phases are mandatory

Before the two phases, the audit MUST run a lightweight structural
pre-pass:

- **Pre-pass — Template conformance:** check that each in-scope user
  story conforms to `papi-sdlc-user-stories`' `user-story-template.md`,
  the user-stories index conforms to `user-stories-template.md`, and
  each component spec referenced by a cited or in-scope capability
  conforms to `papi-sdlc-component-specification`'s
  `component-specification-template.md`. Record any structural drift
  (missing sections, renamed fields, stale guidance, undocumented
  additions) as findings with a disposition: **update document** /
  **update template** / **accept with note**. This pass separates
  "format outdated" from "content wrong" before Phase A goes deeper.

A fulfilment audit MUST then run in two directions and reconcile the
results:

- **Phase A — Top-down (story → capability):** for each user story in
  scope, gather the user-facing capabilities whose `**Users:**` field
  cites that story, and check:
  - at least one capability cites the story (a story cited by none is
    unfulfilled)
  - every citing capability is **user-facing** (its `**Users:**` field
    cites one or more user stories; `internal` and `composition`
    capabilities MUST NOT cite stories)
  - the story's `**Role:**` matches the role recorded against it in
    each citing capability's `**Users:**` field
  - the citing capabilities are plausibly aligned with what the story
    asks for
  - the union of citing capabilities is sufficient to cover the
    story's narrative and acceptance criteria
  - Classify the story as: **Covered**, **Partial**, **Missing**, or
    **Misaligned**.

- **Phase B — Bottom-up (capability → story):** Phase B sweeps only
  **user-facing capabilities**, i.e. those whose `**Users:**` field
  cites at least one user story (capabilities marked `internal` or
  `composition` are out of scope for this audit and belong in the
  Excluded list).

  For each user-facing capability in scope, resolve the user stories
  it cites. Check:
  - every story it cites exists and is in scope
  - the role recorded against each cited story matches that story's
    own `**Role:**` field

  Capabilities citing no real in-scope story are **orphan
  candidates**. Capabilities whose cited stories exist but carry a
  mismatched role are **role-coverage gaps** (the capability is in
  use, but misattributes who it serves).

  An orphan capability is one of two kinds:
  - *scope creep* — the capability exists but no user wants it
  - *missing story* — a user does want it, but the story hasn't
    been written

  (A capability that is genuinely not user-facing should never reach
  this list — if one does, the finding is *mismarked user-facing*:
  update the spec to mark it `internal` or `composition`.)

- **Phase C — Reconciliation:** merge Phase A gaps, Phase B orphan
  capabilities, and Phase B role-coverage gaps into a single
  findings list. For each finding, record the agreed disposition:
  - **Update stories** (add, change, fix capability links, add a
    missing story for a role)
  - **Update specs** (add, change, or remove capabilities; mark a
    capability `internal` or `composition`; correct a `**Users:**`
    role list)
  - **Accept with note** (a deliberate, recorded exception)

Running only Phase A is a CRITICAL FAILURE: it lets user-facing
capabilities that serve no story persist in the specs unchallenged.
Both phases must be evidenced in the report.

### Orphan candidate handling

Every Phase B orphan capability MUST be brought to the user for a
disposition decision before the audit closes. Do NOT auto-classify
the orphan kind — the choice between scope creep and missing story

From stainsby/papi, MIT.

More from stainsby/papi