# Story 17.19: Rework story-status-lookup Skill (Light Rework -- Cross-Section Search)

Status: review

## Story

As a **Developer**,
I want the `story-status-lookup` skill to search the unified `sprint-status.yaml` schema (backlog array and sprints[].items arrays) for any story's current status,
So that code can be classified as delivered or work-in-progress from a single data source without relying on the deprecated flat `development_status` map.

## Acceptance Criteria

1. **Given** the `story-status-lookup` skill is invoked with a story ID,
   **When** the story exists in the `backlog` array of `sprint-status.yaml`,
   **Then** it returns the item's `status` field value and notes it is "in backlog (unassigned)".

2. **Given** the story exists in a sprint's `items` array,
   **When** the lookup completes,
   **Then** it returns the item's `status` field value and notes which sprint it is assigned to (e.g., "in sprint-3").

3. **Given** the story is not found in any section of `sprint-status.yaml`,
   **When** the lookup checks the `done/` archive folder,
   **Then** it reports "Story {id} is archived (done)" if a file matching `{story_location}/done/{id}.md` exists,
   **And** classifies the story as **delivered**.

4. **Given** the story is not found in `sprint-status.yaml` AND not found in the `done/` archive,
   **When** the lookup completes,
   **Then** it reports "Story {id} not found in sprint-status.yaml or done/ archive",
   **And** classifies the story as **WIP** (per the existing fallback rule: when in doubt, WIP).

5. **Given** the status-to-classification mapping (delivered vs WIP),
   **When** the skill returns a result,
   **Then** the classification table is unchanged from the current implementation:
   | Status | Classification |
   |--------|---------------|
   | `done` | Delivered |
   | `review` | Delivered |
   | `in-progress` | WIP |
   | `ready-for-dev` | WIP |
   | `backlog` | WIP |
   | `on-hold` | WIP |
   | `cancelled` | WIP |

6. **Given** the skill source file exists at `skills/story-status-lookup/SKILL.md` (IDE skill pipeline),
   **When** the ma-agents installer is run,
   **Then** the IDE skill is deployed to all agent directories via `lib/installer.js` (`performInstall`),
   **And** the installed copies are byte-identical to the source (minus frontmatter injection by the installer),
   **And** `always_load: true` remains set in `skill.json` so the skill loads for every agent task.

7. **Given** the skill's Backend Configuration section supports file-system and Jira backends,
   **When** the Jira backend is not yet implemented,
   **Then** the "Future: Jira Backend" section is preserved unchanged for Story 17.22 activation.

## Agent Discussion: IDE Skill Only -- No BMAD Extension

**Winston (Architect):** `story-status-lookup` is fundamentally different from sprint management workflow skills. It is a passive, read-only lookup used by all agents to classify code. It has no BMAD-specific context requirements -- no config loading from `_bmad/bmm/config.yaml`, no XML workflow semantics, no multi-file delegation. It reads one file (`sprint-status.yaml`) and returns a status string. The IDE skill pipeline (`lib/installer.js`) already deploys it to all agent directories, and BMAD agents receive it through the same mechanism. Creating a BMAD extension version would mean maintaining two copies of the same trivially simple skill with zero functional divergence.

**John (PM):** The acceptance criteria cover all agents via AC 6 -- the installer deploys to everyone. There is no agent-specific behavior to differentiate. A BMAD extension would add maintenance overhead (two SKILL.md files, a bmad-skill-manifest.yaml, a module-help.csv entry) for zero user-facing value. The skill has `always_load: true` -- it is already loaded for every BMAD agent task via MANIFEST.yaml. No BMAD user would benefit from a separate extension version.

**Mary (Analyst):** The PRD (FR120) says sprint artifacts resolve paths from `{sprint_management_path}`. The skill already uses `_bmad-output/implementation-artifacts/sprint-status.yaml` from the project root, which is the correct default for single-repo mode. Multi-repo path resolution is a Story 17.22/17.23 concern and applies uniformly to all skills. No PRD requirement mandates BMAD-specific behavior for passive status lookup. The epics.md technical notes for 17.19 say "Reworks the existing skill" -- confirming the intent is to update the existing IDE skill, not create a new BMAD extension.

**Decision: IDE skill only (`skills/story-status-lookup/`). No BMAD extension version.**

## Tasks / Subtasks

### Task 1: Read and understand the current skill (AC: 1-5, 7)

- [x] 1.1 Read `skills/story-status-lookup/SKILL.md` -- the canonical source file (this is NOT the installed copy). Understand the current three-step flow:
  - Step 1: Slug derivation (from filename, branch, or explicit reference)
  - Step 2: Flat `development_status` map lookup
  - Step 3: Status-to-delivered/WIP classification
- [x] 1.2 Read `skills/story-status-lookup/skill.json` -- confirm metadata and `always_load: true`
- [x] 1.3 Document the current "Backend Configuration" section logic (file-system vs Jira backend selection)

### Task 2: Rewrite Step 2 -- replace flat map lookup with cross-section search (AC: 1, 2)

The current Step 2 says: "Find the slug as a key under `development_status` in `sprint-status.yaml`." Replace this entire step with a cross-section search.

- [x] 2.1 Replace the instruction to look up `development_status[slug]` with a search across two sections:
  - **Backlog search:** Iterate the `backlog` array. For each item, check if `item.id` matches the derived slug.
  - **Sprint search:** Iterate the `sprints` map. For each sprint, iterate its `items` array. For each item, check if `item.id` matches the derived slug.
- [x] 2.2 When found in `backlog`, the result includes: the item's `status` field value + location context "in backlog (unassigned)"
- [x] 2.3 When found in a sprint's `items` array, the result includes: the item's `status` field value + location context "in {sprint-id}" (e.g., "in sprint-3")
- [x] 2.4 Remove ALL references to the `development_status` flat map key format
- [x] 2.5 The search is read-only -- the skill NEVER writes to `sprint-status.yaml`

### Task 3: Implement done/ archive fallback (AC: 3, 4)

If the slug is not found in any section of `sprint-status.yaml`, check the archive before falling back to "not found."

- [x] 3.1 Check for a file at `{story_location}/done/{slug}.md` where `story_location` is the value from the `story_location` metadata field in `sprint-status.yaml` (default: `_bmad-output/implementation-artifacts`)
- [x] 3.2 If the file exists in `done/`, return: "Story {id} is archived (done)" -- classify as **delivered**
- [x] 3.3 If not found anywhere (not in backlog, not in any sprint, not in done/), return: "Story {id} not found in sprint-status.yaml or done/ archive" -- classify as **WIP** per the existing fallback rule

### Task 4: Preserve unchanged skill sections (AC: 5, 7)

- [x] 4.1 **Step 1 (slug derivation)** -- preserve entirely unchanged. The three-method derivation (filename, branch, explicit reference) works regardless of schema format.
- [x] 4.2 **Step 3 (status-to-classification table)** -- preserve the delivered/WIP mapping table. Add `cancelled` status mapped to WIP if not already present (the unified schema adds this status).
- [x] 4.3 **Fallback rule** -- preserve the "When in doubt, WIP" rule. Update it to include the new done/ archive check as an intermediate step before the final WIP fallback:
  1. Slug not determined -> WIP
  2. Slug not found in sprint-status.yaml -> check done/ archive
  3. Found in done/ -> delivered
  4. Not found anywhere -> WIP
  5. Status file does not exist -> WIP
- [x] 4.4 **Backend Configuration section** -- preserve unchanged (file-system vs Jira backend selection logic)
- [x] 4.5 **Future: Jira Backend section** -- preserve unchanged. Story 17.22 will activate this extension point.

### Task 5: Update skill.json if needed (AC: 6)

- [x] 5.1 Read `skills/story-status-lookup/skill.json` and verify:
  - `always_load: true` is present
  - `version` should be bumped to `"2.0.0"` (the lookup mechanism is fundamentally changed)
  - `description` accurately reflects the new behavior -- update if it still references the flat map
- [x] 5.2 Update the `description` field to reflect unified schema search:
  ```json
  "description": "Looks up the current status of a story by searching the unified sprint-status.yaml (backlog and sprint items arrays) to classify code as delivered or work-in-progress. Supports file-system backend; Jira backend reserved for future configuration."
  ```

### Task 6: Deployment verification (AC: 6)

- [x] 6.1 Run `npx ma-agents` (or `node lib/cli.js`) to trigger the installer
- [x] 6.2 Verify the installed SKILL.md for at least one agent (e.g., `.claude/skills/story-status-lookup/SKILL.md`) contains the new cross-section search instructions and does NOT reference `development_status`
- [x] 6.3 Diff the installed copy against the source (`skills/story-status-lookup/SKILL.md`) -- content should match after accounting for frontmatter injection by the installer
- [x] 6.4 Verify `always_load: true` appears in the installed MANIFEST.yaml entry for `story-status-lookup`
- [x] 6.5 Confirm NO `lib/bmad-extension/skills/story-status-lookup/` directory exists -- per the decision to keep this IDE-only

## Dev Notes

### CRITICAL: Source File Location (Read This First)

The source file to modify is:

- **`skills/story-status-lookup/SKILL.md`** -- the canonical skill content
- **`skills/story-status-lookup/skill.json`** -- the skill metadata

These are the SOURCE files in the IDE skill pipeline. The installer (`lib/installer.js`) reads these and deploys copies to all agent directories (`.claude/skills/`, `.cursor/skills/`, `.cline/skills/`, `.roo/skills/`, `.gemini/skills/`, `.github/copilot/skills/`, `.kilocode/skills/`).

**NEVER edit the installed copies directly** (e.g., `.claude/skills/story-status-lookup/SKILL.md`). They are overwritten on every install.

### What This Story Changes vs Current Behavior

**Current behavior (Step 2):** The skill reads `sprint-status.yaml`, finds the story slug as a key under the flat `development_status` map:

```yaml
development_status:
  5-5-explicit-parameter-passing: review
  17-19-rework-story-status-lookup: ready-for-dev
```

It reads `development_status[slug]` and returns the status string.

**New behavior (Step 2):** The skill reads `sprint-status.yaml`, searches for the story ID across two structured sections:

```yaml
backlog:
  - id: "17-19-rework-story-status-lookup"
    status: ready-for-dev
    ...

sprints:
  sprint-3:
    items:
      - id: "5-5-explicit-parameter-passing"
        status: review
        ...
```

It iterates `backlog` items and all `sprints[].items` arrays, matching `item.id` against the slug. When found, it returns both the status and the location context (e.g., "in sprint-3" or "in backlog (unassigned)").

**New behavior (done/ fallback):** If the slug is not found in any section, the skill checks `{story_location}/done/{slug}.md`. If the file exists, the story is classified as delivered (archived). This is a new intermediate step before the existing "not found = WIP" fallback.

### Scope of Changes -- Surgical, Not Full Rewrite

This is a **light rework** because:

- **Step 1 (slug derivation)** is unchanged -- the three-method derivation works regardless of schema format
- **Step 3 (status classification table)** is unchanged -- delivered/WIP mapping is the same
- **Backend Configuration section** is unchanged -- file-system vs Jira selection logic is the same
- **Future: Jira Backend section** is unchanged -- Story 17.22 activates this
- **Only Step 2 (the lookup mechanism)** changes from flat-key to cross-section search
- **One addition:** done/ archive fallback check (new intermediate step in the fallback chain)

The SKILL.md file is approximately 75 lines. The change touches roughly 15-20 lines in the Step 2 section and adds approximately 10 lines for the done/ archive fallback.

### Cross-Section Search Pattern

The search pattern is consistent with Story 17.18 (`bmad-dev-story`) and Story 17.13 (`sprint-status-view`):

```
Search order:
  1. backlog array -- iterate items, match item.id == slug
  2. sprints map -- iterate each sprint's items array, match item.id == slug
  3. done/ folder -- check for file existence at {story_location}/done/{slug}.md
  4. Not found -- classify as WIP
```

Unlike `bmad-dev-story` (which prioritizes active sprints for auto-discovery), this skill does NOT need to prioritize by sprint status -- it just needs to find the item wherever it lives. Search order does not affect the result.

### Why No BMAD Extension Version

Per the agent discussion above, this skill:
- Has no BMAD-specific context requirements (no config loading, no XML workflows, no multi-file delegation)
- Is already deployed to all agents via `lib/installer.js` (including BMAD agents)
- Is `always_load: true` -- loaded for every task in every agent
- Would require maintaining two identical SKILL.md files for zero functional benefit

This is unlike `bmad-dev-story` (Story 17.18) which requires BMAD agent context, or `generate-backlog` (Story 17.10) which has BMAD-specific phrasing. `story-status-lookup` is agent-agnostic and pipeline-1-only.

### Unified Schema Sections Touched

- **`backlog`** -- searched for item by `id` (read-only)
- **`sprints`** -- all sprint entries' `items` arrays searched for item by `id` (read-only)
- **Metadata** -- `story_location` field read to resolve the done/ archive path
- This skill is **strictly read-only** -- it NEVER writes to `sprint-status.yaml`

### Reference Files

- **Skill source:** `skills/story-status-lookup/skill.json` + `skills/story-status-lookup/SKILL.md`
- **Schema:** `_bmad-output/planning-artifacts/sprint-status-schema.md` (canonical schema for sprint-status.yaml)
- **Sprint status:** `_bmad-output/implementation-artifacts/sprint-status.yaml`
- **Done archive:** `_bmad-output/implementation-artifacts/done/`
- **MANIFEST:** `.claude/skills/MANIFEST.yaml` (installed manifest -- verify `always_load: true` entry)

### Cross-References

- **Story 17.9** (prerequisite, done): Defines the unified `sprint-status.yaml` schema this skill searches
- **Story 17.18** (parallel): `bmad-dev-story` uses the same cross-section search pattern for finding items by `id`. The search logic should be consistent between both skills.
- **Story 17.13** (parallel): `sprint-status-view` reads all sections for summary display -- similar read-only traversal
- **Story 17.22** (downstream): Jira adapter pattern -- will activate the Jira backend extension point preserved in this skill
- **Story 17.23** (downstream): Migration/deprecation -- will remove the legacy `development_status` map from `sprint-status.yaml`; this skill must be updated BEFORE that migration runs
- **Epic 11** (consumer): `auto-bug-detection` skill consumes this skill's delivered/WIP classification. The classification table must remain compatible.

### Gotchas and Warnings

1. **The current SKILL.md explicitly says "Find the slug as a key under `development_status`" in Step 2.** This sentence and surrounding instructions must be fully replaced -- do not leave any reference to the flat map.
2. **The `cancelled` status** is new in the unified schema (Section 6.6 of the schema doc). It should map to WIP in the classification table if not already present.
3. **The done/ archive check is a NEW addition** to the fallback chain. The current skill has no done/ check -- it goes directly from "not found" to "classify as WIP." The new chain is: not found in file -> check done/ -> found = delivered, not found = WIP.
4. **The `story_location` metadata field** in `sprint-status.yaml` provides the path to the implementation artifacts directory. Use this to resolve `{story_location}/done/{slug}.md` rather than hardcoding `_bmad-output/implementation-artifacts`.
5. **This skill must be updated BEFORE Story 17.23 (migration)** runs. Story 17.23 will remove the `development_status` map from `sprint-status.yaml`. If this skill still reads `development_status` when migration runs, all lookups will fail (fallback to WIP, which is safe but incorrect for delivered stories).
6. **The `always_load: true` flag means every agent session loads this skill.** Keep the SKILL.md concise -- avoid verbose instructions that waste context window in every session.

### PRD Traceability

- **FR62:** `auto-bug-detection` skill uses this skill's delivered/WIP classification to decide whether to flag bugs -- the classification must remain compatible after rework
- **FR65:** "All sprint, backlog, and epic status data is managed in a single sprint-status.yaml" -- this skill now reads from the unified three-section file
- **FR120:** "All BMAD workflows that produce or consume sprint artifacts resolve their paths from the configured `{sprint_management_path}`" -- this skill reads `sprint-status.yaml` from the implementation artifacts path
- **FR134:** "Each item carries a consistent structure (id, type, epic, title, priority, status, severity)" -- the cross-section search matches items by their `id` field
- **FR135:** "Each item carries its own status field, updated in-place within the section where it resides" -- this skill reads the result of those in-place status updates

### Architecture Reference

- Architecture Decision P2-11 in `_bmad-output/planning-artifacts/architecture.md` -- Unified Sprint-Status Data Architecture
- Skill Integration Map in architecture doc and schema doc (Section 7) -- `story-status-lookup` listed as "Light" rework, operating on all sections (read-only)

---

## Dev Agent Record

**Agent:** Claude Sonnet 4.6 (claude-sonnet-4-6)
**Date:** 2026-04-06
**Branch:** feature/story-17-19-story-status-lookup
**Worktree:** `.worktrees/story-17-19-story-status-lookup/`

### Implementation Summary

Reworked `skills/story-status-lookup/SKILL.md` to replace the flat `development_status` map lookup (Step 2) with a cross-section search across the unified `sprint-status.yaml` three-section schema. Updated `skill.json` to version 2.0.0. Ran the installer to deploy the updated skill to the claude-code agent directory for verification.

### Code Review Findings

1. **All three search locations covered** — backlog array (2a), all sprints[].items arrays (2b), and done/ archive (2c). PASS.
2. **Location context returned** — skill reports "in backlog (unassigned)" or "in {sprint-id}" or "archived (done)". PASS.
3. **Story not found handled** — Step 2d reports "Story {id} not found in sprint-status.yaml or done/ archive" and classifies as WIP. PASS.
4. **Read-only** — skill contains no write instructions. PASS.
5. **Deployment verification** — installer v2.0.0 deployed to `.claude/skills/story-status-lookup/SKILL.md`; no `development_status` reference in installed copy; `always_load: true` in MANIFEST.yaml; no BMAD extension directory. PASS.
6. **`cancelled` status** — added to classification table mapping to WIP (was missing from original). PASS.
7. **Fallback rule** — rewritten as ordered list with done/ archive as intermediate step before final WIP. PASS.
8. **Jira Backend section** — preserved unchanged. PASS.

No issues found requiring fixes.

---

## File List

### Modified
- `skills/story-status-lookup/SKILL.md` — Reworked Step 2 (flat map → cross-section search), added done/ archive fallback, updated fallback rule list, added `cancelled` to classification table
- `skills/story-status-lookup/skill.json` — Bumped version to 2.0.0, updated description
- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Set `17-19-rework-story-status-lookup: in-progress` (updated to `review` at completion)
- `_bmad-output/implementation-artifacts/17-19-rework-story-status-lookup.md` — Marked all tasks complete, set Status to review, added Dev Agent Record / File List / Change Log

### Installed (auto-generated by installer — do not edit directly)
- `.claude/skills/story-status-lookup/SKILL.md`
- `.claude/skills/MANIFEST.yaml`

---

## Change Log

| Date | Author | Change |
|------|--------|--------|
| 2026-04-06 | Claude Sonnet 4.6 | Initial implementation: replaced flat `development_status` lookup with cross-section search across backlog, sprints, and done/ archive; bumped skill.json to v2.0.0; added `cancelled` status to classification table; rewrote fallback rule as ordered list |
