From pharaoh
Analyzes impact of changes to sphinx-needs requirements, specs, or items by tracing links, extra_links, and codelinks to affected needs and code files.
How this skill is triggered — by the user, by Claude, or both
Slash command
/pharaoh:pharaoh-changeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill's visible output is the full **Change Document** as defined in Step 5. The document is mandatory. Every invocation MUST emit the complete document with all sections. The session-state update in Step 4 is internal bookkeeping and MUST NOT replace the document. Step 5 is the LAST major section of the skill before Strictness Behavior, so the Change Document is the final visible content ...
This skill's visible output is the full Change Document as defined in Step 5. The document is mandatory. Every invocation MUST emit the complete document with all sections. The session-state update in Step 4 is internal bookkeeping and MUST NOT replace the document. Step 5 is the LAST major section of the skill before Strictness Behavior, so the Change Document is the final visible content of the turn.
Failure modes:
Non-interactive callers cannot reach the document past a follow-up prompt. The skill MUST be self-terminating. Acknowledgment is checked by downstream enforcing-mode authoring skills (pharaoh-author, pharaoh-req-regenerate, etc.) against the session-state flag. They FAIL with a message naming the file path and the field to flip.
Analyze the full impact of a proposed change to any sphinx-needs item. Trace through ALL link types -- standard links, extra_links (implements, tests, etc.), and sphinx-codelinks -- to produce a structured Change Document listing every affected need and code file with a recommended action.
This is a gate-free skill. It can be invoked at any time in any strictness mode. Authoring skills depend on its output.
Before accessing any project data, establish exactly what is being changed.
Extract from the user's request:
REQ_001, SPEC_002). If the user describes the need by title or content instead of ID, note it and resolve the ID in Step 2.If the user's request is ambiguous, ask exactly one round of clarifying questions before proceeding. Cover only what is missing:
Do not ask questions whose answers can be determined from the project data.
Follow the instructions in skills/shared/data-access.md to detect the project structure and build the needs index. Specifically:
ubproject.toml, conf.py, and the documentation source tree.ubc build needs --format json for the complete needs index.After data access completes, present a brief detection summary:
Project: <name> (<config source>)
Types: <list of directive names>
Links: <list of link type names>
Data source: <tier used>
Needs found: <count>
Codelinks: <enabled/disabled/not configured>
Strictness: <advisory/enforcing>
If the user described the target need by title or content rather than ID, search the needs index now. Match by:
If multiple needs match, list them and ask the user to confirm which one(s) to analyze. If exactly one matches, proceed with it and inform the user of the resolved ID.
With the needs index, link graph, and target need(s) identified, perform a full impact analysis.
Find every need that is directly linked to ANY target need. Check all link directions:
links, implements, tests, and all other extra_link options.links, implements, tests, or other extra_link options reference the target's ID.outgoing and incoming directions as defined in the project configuration.For each directly linked need, record:
links, implements, tests)Starting from the set of directly impacted needs, recursively follow all links to find transitively affected needs.
Algorithm:
visited = set(target_ids)
queue = [all directly impacted needs]
distance = {direct_need: 1 for direct_need in queue}
while queue is not empty:
current = queue.pop(0)
for each need linked to current (all link types, both directions):
if need.id not in visited:
visited.add(need.id)
distance[need.id] = distance[current.id] + 1
queue.append(need)
Stop conditions:
For each transitively impacted need, record:
Perform this step only if sphinx-codelinks is enabled (detected in Step 2 or configured in pharaoh.toml).
For every need in the affected set (direct + transitive), search for code files that reference the need's ID via codelink annotations.
Search strategy:
# codelink: <NEED_ID>// codelink: <NEED_ID>/* codelink: <NEED_ID> */conf.py or ubproject.toml.Exclude documentation directories (docs/, _build/) and common non-source directories (node_modules/, .git/, __pycache__/).
For each code file found, record:
For each affected item (need or code file), classify the required action:
Must update -- The change directly invalidates this item. Apply when:
Review needed -- The change may affect this item but requires human judgment. Apply when:
No change needed -- The item is linked but unaffected by this specific change. Apply when:
Classification rules:
This step is internal bookkeeping. It writes the change-analysis record to .pharaoh/session.json and emits NOTHING to the visible turn output. The Change Document is emitted in Step 5 (the final visible action of the turn).
Follow the session state instructions in skills/shared/strictness.md (Section 4).
.pharaoh/session.json exists..pharaoh/ directory and initialize the session state:{
"version": 1,
"created": "<current ISO 8601 timestamp>",
"updated": "<current ISO 8601 timestamp>",
"changes": {},
"global": {
"mece_checked": false,
"mece_timestamp": null,
"last_release": null
}
}
For each target need ID, add or update an entry in the changes dictionary:
{
"changes": {
"<TARGET_ID>": {
"change_analysis": "<current ISO 8601 timestamp>",
"acknowledged": false,
"authored": false,
"verified": false
}
}
}
Key points:
change_analysis to the current timestamp.acknowledged to false. Downstream enforcing-mode authoring skills check this flag and the user flips it by editing the session-state file directly.authored or verified if the entry already exists -- preserve those values.updated timestamp.Write the updated JSON to .pharaoh/session.json. Ensure the JSON is properly formatted (indented for readability).
This is the visible output of the skill. After Step 4 has written session state, emit the full Change Document below as the final action of the turn. The document is the LAST instruction of the skill. Do NOT ask any follow-up question. End the turn after emitting.
Use the structured format below. Use markdown tables for readability. Omit sections that have no rows but always emit the Change Request, Summary, and Recommendation header lines.
## Change Document
### Change Request
- **Target**: <NEED_ID> (<need title>)
- **Change**: <plain-language description of the change>
- **Requested by**: user
- **Date**: <current ISO 8601 date>
### Direct Impact (1 hop)
| Need ID | Type | Title | Link Type | Direction | Action |
|---------|------|-------|-----------|-----------|--------|
| <ID> | <type> | <title> | <link_type> | <in/out> | <Must update / Review needed / No change needed> |
### Transitive Impact
| Need ID | Type | Title | Distance | Path | Action |
|---------|------|-------|----------|------|--------|
| <ID> | <type> | <title> | <N hops> | <link chain> | <Must update / Review needed / No change needed> |
### Code Impact
| File | Location | Linked Need | Action |
|------|----------|-------------|--------|
| <relative path> | <function/line> | <NEED_ID> | <Must update / Review needed> |
If codelinks are not enabled or no code references are found, display:
> No code impact detected. sphinx-codelinks is not configured for this project.
or:
> No code files reference the affected needs via codelinks.
### Summary
- **Needs requiring update**: <count>
- **Needs requiring review**: <count>
- **Needs with no change needed**: <count>
- **Code files affected**: <count>
- **Total items in impact scope**: <count>
- **Maximum traversal depth**: <N hops>
- **Recommendation**: <proceed / escalate / discuss>
Recommendation logic:
safety, critical, or regulatory (or similar domain-specific tags) is classified as "Must update", OR more than 10 items require update.If the user requested changes to multiple needs, produce one Change Document per target need. If the impact sets overlap, note the overlap at the end:
### Overlap
The following needs appear in the impact scope of multiple targets:
- <NEED_ID>: affected by both <TARGET_1> and <TARGET_2>
Acknowledgment is NOT part of this skill's output. Do not ask the user to acknowledge the analysis. Downstream behavior:
acknowledged. The user proceeds freely..pharaoh/session.json[changes][<id>].acknowledged and FAIL with a message naming the file path and the field to flip. The user edits the session-state file directly to acknowledge.This split keeps pharaoh-change non-interactive and CI-safe.
End the turn after emitting the Change Document.
Follow the instructions in skills/shared/strictness.md for strictness handling. The specifics for this skill:
acknowledged flag in session state remains false. Other skills will show a tip but will not block.skills/shared/strictness.md Section 3, "Skills with no gates")..pharaoh/session.json for acknowledged: true on the relevant need IDs.Both advisory and enforcing modes perform the same analysis. Strictness only affects whether downstream skills gate on the results.
If the ubc CLI is available (detected in Step 2), use ubc diff to supplement or replace parts of the manual impact analysis.
ubc diff
or with a specific baseline:
ubc diff --base <ref>
ubc diff returns a structured diff including:
If ubc diff provides impact tracing:
If ubc diff does not provide impact tracing (older version), use it only for identifying which needs changed, then perform the full manual analysis from Step 3.
If the target need ID is not found in the needs index:
If the target need has zero outgoing and zero incoming links:
If the link graph contains cycles (A links to B, B links to C, C links to A):
visited set, so cycles are handled automatically.Note: Circular link chain detected: <A> -> <B> -> <C> -> <A>. Each need appears once in the impact analysis.
If the analysis yields more than 50 affected needs:
Warning: This change has a large impact scope (N needs). Consider breaking the change into smaller increments or reviewing the link structure for overly broad connections.
If the workspace contains multiple sphinx-needs projects and the target need links to needs in a different project:
| SPEC_EXT_001 | Specification | External sensor spec | 1 hop | Review needed | (project: sensor-subsystem) |
Handled in Step 2a. If the user says "change the brake response time requirement", resolve to REQ_001 using title matching, then proceed normally.
To illustrate the full process, here is a walkthrough using the Brake System test fixture.
User request: "Change REQ_001 latency from 100ms to 50ms"
Step 1 -- Target: REQ_001 (Brake response time). Nature: value change. Change: response time threshold from 100ms to 50ms.
Step 2 -- Data access detects:
Project: Brake System (ubproject.toml)
Types: req, spec, impl, test
Links: links, implements, tests
Data source: Tier 3 (raw file parsing)
Needs found: 8
Codelinks: not configured
Strictness: advisory
Step 3 -- Impact analysis:
Direct (1 hop from REQ_001):
SPEC_001 -- linked via links (incoming: SPEC_001 links to REQ_001). Content mentions "10ms signal update rate" -- related to timing. Action: Must update (spec for the sensor interface must reflect the tighter timing budget).REQ_002 -- linked via links (incoming: REQ_002 links to REQ_001). Content about "force distribution" -- different property. Action: Review needed (sibling requirement, may have implicit timing dependency).Transitive:
SPEC_002 -- 2 hops (REQ_001 -> REQ_002 -> SPEC_002 via links). Content about "force distribution algorithm". Action: No change needed.IMPL_001 -- 2 hops (REQ_001 -> SPEC_001 -> IMPL_001 via links/implements). Content about "CAN driver for brake pedal sensor". Action: Review needed (driver timing may need adjustment for 50ms budget).TEST_001 -- 3 hops (REQ_001 -> SPEC_001 -> IMPL_001 -> TEST_001 via links/implements/tests). Content: "Verify brake response within 100ms". Action: Must update (test threshold must change to 50ms).IMPL_002 -- 3 hops (REQ_001 -> REQ_002 -> SPEC_002 -> IMPL_002 via links/implements). Action: No change needed.TEST_002 -- 4 hops (via IMPL_002). Action: No change needed.Code impact: Not applicable (codelinks not configured).
Step 4 -- Session state written: REQ_001 entry with acknowledged: false. No visible output from this step.
Step 5 -- Change Document emitted with the tables above. Summary: 2 must update, 2 review needed, 3 no change needed, 0 code files. Recommendation: proceed. Turn ends after emission. Session state holds acknowledged: false. The user edits .pharaoh/session.json directly to flip the flag before invoking an enforcing-mode authoring skill.
npx claudepluginhub useblocks/pharaoh --plugin pharaohBreaks requirement changes into ordered actionable tasks with Pharaoh workflow enforcement and dependency ordering for sphinx-needs projects.
Performs graph-based impact analysis to answer 'if I change X, what breaks?' before merging PRs or planning refactors.
Processes increment-request.json: orients on project state, elicits incremental EARS requirements with acceptance criteria, classifies changes, updates SRS/design docs, appends to feature-list.json.