Assess Change Impact

Assess Change Impact — Skill Instructions

What this skill answers

"If we change TMFC020 (or TMF632, or a specific version of it), which use cases break, how exactly do they depend on it, and how risky is that?"

Step 1 — Identify the id type and look it up

TMFCxxx is a component, TMFxxx (not TMFCxxx) is an API — the id's own shape tells you which without asking. Look it up in the matching index file:

knowledge/index/components.json   -- one row per component, keyed by id
knowledge/index/apis.json         -- one row per (id, version) pair

Components are unique per id — components.json has exactly one row per TMFCxxx, so there's no ambiguity to resolve.

APIs are not — apis.json can have multiple rows for the same id at different versions, since more than one version of an API can be cached side by side. If the proposed change is version-specific ("deprecating v4 in favor of v5"), match on both id and version and report only that version's used_by — merging across versions would overstate the blast radius of a version-specific change. If the caller hasn't specified a version, list every cached version's used_by separately, not merged into one number.

If the id isn't in the index at all, say so plainly — don't guess a nearby id. A component with status: "not_yet_specified" or an API with status: "fetch_failed" has no real spec to change yet; report that directly rather than proceeding as if it had one.

Step 2 — Read used_by

Every row in components.json/apis.json carries a used_by field — this is the starting "which use cases depend on this" list. Its shape differs by artefact type, deliberately, and both differences matter to what you report:

components.json's used_by is already reconciled — tools/build_index.py builds it as the union of each use case's own frontmatter (links.components) and IG1228's independently-sourced usecase-component-matrix.json, so it's a list of {use_case, source} entries rather than a bare id list:

• source: "confirmed" — both the use case's own document and IG1228's matrix agree.
• source: "frontmatter_only" — the use case's own document names this component; IG1228's matrix doesn't credit it.
• source: "matrix_only" — IG1228's matrix credits this use case with the component; the use case's own document doesn't say so. Per knowledge/index/matrix-discrepancies.md's Phase 4 findings this is the more common of the two disagreement directions, not the rarer one — report these use cases as real, reportable dependents (noting the source), not as a footnote under the confirmed ones. Overall, matrix-discrepancies.md's corpus-wide check found the two sources disagree for the majority of use cases (14 of 24), so expect frontmatter_only/matrix_only entries often, not rarely.

No separate matrix lookup is needed for a component id — the reconciliation already happened when the index was built. Group the report by source (§ Output format) rather than treating used_by as one flat list.

apis.json's used_by is a plain frontmatter-derived id list, with no source tag — IG1228 chapter 2's matrix is a use-case↔component table; it has no API-level data at all, so there's nothing to reconcile against for a TMFxxx id (confirm the file's usecase-component-matrix.json carries no apis key rather than assume it). State this plainly rather than implying an API id got the same two-source reconciliation a component id gets — those are genuinely different completeness guarantees, and the difference matters to a reviewer deciding how much to trust the number.

Separately, a component/API can also be named only in a use case's body prose rather than its References section (like TMFS020's own TMFC001/002/023) — neither used_by nor the matrix catches that, since both are References-section-derived. Step 4's own document read is what surfaces this category — a third, smaller way used_by can undercount, worth keeping in mind alongside the matrix gap above.

Step 3 — Cross-check each affected use case's own maturity

For every use case in used_by (each entry's use_case field for a component id; each plain id for an API id), look up that row in knowledge/index/use-cases.json and read its maturity/approval_status/release_status fields (the same ones check-usecase-maturity reads):

• GA / TM Forum Approved use cases are firm, stable dependents — a breaking change here has real consumers relying on the current shape.
• Alpha/Beta use cases are still provisional themselves (per check-usecase-maturity's own decision table) — a dependent that's itself not yet settled is lower-risk to disrupt than one that's GA.

Step 4 — Describe specifically how each affected use case depends on it

A bare id + maturity level isn't enough detail to act on — read each affected use case's own document to find how it actually uses the component/API, the same way generate-test-cases-from-usecase resolves a use case's real interaction flow:

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

Search the # Description and # Sequence diagrams sections for where the target id (or its name) actually appears, including the diagram images themselves where relevant — the real step-by-step usage often lives there, not just in a components list. Summarize specifically what the use case does with it (e.g. "TMFC020 verifies the customer's identity at account-creation step 2, before Party Management proceeds" rather than "TMFS001 depends on TMFC020"). This is what turns "6 use cases are affected" into something a reviewer can actually act on — which specific step in each use case's flow needs a migration plan, not just which ids are on a list.

For a long used_by list, prioritize this detailed read for the highest-risk (GA/TM Forum Approved) dependents first — do all of them if asked, but don't let a large list become an excuse to skip Step 4 entirely for the ones that matter most.

Output format

A short report, not a raw dump of used_by. Example, for "deprecating TMF632 v4.0.0":

TMF632 v4.0.0 (Party Management, currently generation v4) — 6 use cases depend on it via their own frontmatter:

Use case	Maturity / approval	Risk	How it's actually used
TMFS001	GA / TM Forum Approved	High	Creates the Individual resource at account-creation step 3; also read/updated later for profile changes
TMFS006	GA / TM Forum Approved	High	Looks up the existing Individual to attach a Legal Guardian relationship
TMFS030	Beta / Member Evaluated	Low — itself still provisional	References the Party as the MNO/SNO contracting entity, not a core flow step

4 of 6 dependents are GA — a breaking change to TMF632 v4 needs a migration path for those before it ships, starting with TMFS001's create-and-update flow since it's the deepest dependency. TMF632 is an API id, so used_by is apis.json's plain frontmatter-derived list — IG1228's matrix has no API-level data to reconcile against (Step 2).

For a TMFCxxx id, the same table gains a Source column (confirmed / frontmatter_only / matrix_only, straight from components.json's own used_by entries) instead of that closing caveat — e.g. "6 of 9 dependents confirmed by both sources; 3 are matrix-only (IG1228 credits them, the use case's own document doesn't)." Always state which of the two cases actually applied for this particular id — the reconciled component table or the frontmatter-only API list — not just that the distinction exists in the abstract.

What this skill does NOT do

• Does not modify anything — this is a read-only impact report to inform a human decision, not an automated approval or rejection of the change.
• Does not assume used_by is exhaustive even after reconciliation — a component/API named only in a use case's body prose (Step 2's closing note) is still invisible to both sources, and Step 4's document read is required to catch it for the high-risk dependents at least.
• Does not treat a component id's matrix_only dependents as a footnote — they get reported with the same weight as confirmed ones, per Step 2.
• Does not imply an API id got the same two-source reconciliation a component id gets — apis.json's used_by has no source tag at all, and the report says so rather than staying silent about it.
• Does not stop at a bare id list — Step 4's per-use-case detail is required for at least the high-risk dependents, not an optional enrichment.