Feedback Harvest Gaps From Lessons Learned

Harvest Gaps from Lessons Learned — Skill Instructions

What this skill answers

"What capability gaps has TM Forum's own use-case corpus already identified, that nobody has aggregated into one place?" This skill is for a contributor deciding what ODA should build next, not a consumer building against what already exists — the output should read as a backlog for that audience, not as a build-against-this-today reference.

21 of the 24 converted use cases carry both a ## Lessons learned and ## Impacts identified subsection under their closing # Conclusion, and these sections are where authors record things they noticed were missing while writing the use case — sometimes with a real JIRA/TAC ticket already open, sometimes not. This is real, already-written contributor intent sitting unindexed in knowledge/use-cases/**, not something to infer or guess at.

Step 1 — Read the Lessons learned / Impacts identified section of every use case

knowledge/use-cases/{ID}/{ID}.md

Find ## Lessons learned (heading text and presence varies slightly — TMFS018 nests "Impacts identified" as a subheading under "Lessons learned" rather than as a sibling; TMFS009 has neither) and read through to the next # Conclusion-level section or # Appendix, whichever comes first. Don't read the whole document — this section only. If a use case has neither section (checked: only TMFS009, as of the current corpus), skip it and don't fabricate content for it.

Step 2 — Classify what you find; most of it is NOT this skill's target

The volume of content here is large, and most of it is not a "new component/API" gap — don't harvest everything indiscriminately:

• Enhancement requests to an existing API ("add a PATCH operation," "add an attribute for X," most AP-xxxx/ISA-xxxx JIRA tickets) — these are evolution of something that already exists. Not this skill's target; there are far too many of these across the corpus to aggregate meaningfully, and they don't represent a missing asset.
• SID (Information Framework) gaps (e.g. "SoftwareSupportPackageSpec is missing in SID") — real gaps, but knowledge/sid/ is reserved and empty, with nothing to cross-check against yet. Note these separately, lightly, without trying to verify them against a corpus that doesn't exist locally.
• What this skill IS looking for: an explicit proposal for a component or API that doesn't exist at all yet — signaled by a TMFCxxx/TMFxxx written with no real number (literal TMFCxxx/TMFxxx as placeholder text, not a redacted real id — same convention documented in generate-test-cases-from-usecase/SKILL.md), by prose like "a new component should be introduced," "there is no component exposing X," or by a TAC-xxxx-tracked "Create and Publish: TMFCxxx New ODA Component for..." ticket.

Step 3 — Corroborate across use cases before treating anything as a single data point

The same gap is frequently raised independently, in different words, by multiple use cases written at different times — reading one document at a time misses this entirely. A real example, not a hypothetical: an "API exposure / gateway" gap for B2B component-boundary translation is raised independently by TMFS018 (BuyerGW/SellerGW, tracked as TAC-841), TMFS021 (needs an exposure layer, no ticket), TMFS026 ("Open Gateway Façade"), and TMFS030 (formalizes it as a proposed "Delegate Component" type, citing a named Accelerate 2026 proposal) — four different documents, four different names for what is recognizably the same architectural gap. Don't report these as four separate backlog items; report one item citing all four sources, with TMFS030's as the most mature articulation since it's the most recent and most detailed.

Similarly, TMFS008 and TMFS011 independently cite the same JIRA ticket (TAC-280, "Service & Resource Orchestration") for a fallout/exception-handling capability — that shared ticket id is the corroboration signal, not something to infer from prose similarity alone.

Step 4 — Cross-check every surviving gap against the current corpus

For each gap that survives Step 2/3, check knowledge/index/components.json and knowledge/index/apis.json for anything matching the proposed name or capability — a gap identified two years ago may already be resolved. A real example: TMFS030 itself notes "That gap is addressed in TMFC027 v2.2.0, which was not yet available when this document began but has since appeared" for a different, smaller gap in the same document. Don't trust a use case's own gap list as still-current without checking; report a gap as resolved (with the id that resolved it) rather than repeating stale information, and report a gap as still-open only after actually checking, not by assumption.

Also distinguish two different kinds of "missing" — don't conflate them in the backlog: a component id that's already assigned but status: "not_yet_specified" in components.json (TM Forum has reserved the id, e.g. TMFC033 "Purchase Management" per TMFS020's own frontmatter, just hasn't published the spec) is a different, more advanced stage than a gap with no id assigned at all yet (the literal TMFCxxx placeholder cases from Step 2). Label each backlog entry with which stage it's at.

Step 5 — On a re-run, reconcile with the existing backlog rather than overwrite it blind

knowledge/index/gaps-backlog.md is a persistent, hand-maintained file, not a disposable report — check whether it already exists before writing. If it does, read every entry already logged there and re-run Step 4's cross-check on each one exactly as you would a freshly-found gap: a gap open when it was last logged can resolve between runs (this has already happened once in this corpus — a reservation-component gap was later found to be resolved by a component that started exposing the needed API, and the file was corrected in place rather than left stale). Merge newly-harvested gaps in alongside what's already there; don't regenerate the file from scratch and silently drop a correction someone already made to an existing entry unless your own Step 4 check finds something that actually supersedes it.

Output format

A consolidated backlog, one entry per genuinely distinct gap (post-corroboration), each with: a short name, every use case that raises it (not just the first one found), any JIRA/TAC ticket ids cited, its current status per the Step 4 cross-check, and which corpus stage it's at (no id assigned / id assigned but not_yet_specified). Write this to knowledge/index/gaps-backlog.md, in the same spirit as knowledge/index/matrix-discrepancies.md — a logged, dated finding, not a one-off answer to a single query, since the value here is in the corpus-wide aggregation surviving past this one run.

What this skill does NOT do

• Does not draft the proposed component/API itself — that's propose-component-or-api-extension's job. This skill only finds and consolidates the gap, it doesn't design the fix.
• Does not treat every JIRA-ticketed item as a gap for this backlog — Step 2's filter is required, not optional; a linter-style "count every ticket" run would drown the genuine new-asset gaps in enhancement-request noise.
• Does not report a gap as open without actually checking Step 4 against the current knowledge/index/*.json — "the use case says it's missing" is a starting point, not the final answer.
• Does not overwrite gaps-backlog.md wholesale on a re-run without first reading and re-checking what's already logged there — Step 5's reconciliation is required, not optional, since the file is meant to accumulate and self-correct across runs, not reset each time.