merge: resolve conflict in SKILL.md

Author: sonesuke

docgraph-plugin/skills/ask/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: ask
+description: Documentation Graph Query & Exploration - Find, investigate, and answer questions about the graph.
+---
+
+# Documentation Graph Query & Exploration
+
+This skill provides a structured methodology for exploring the documentation graph and answering specific questions
+about its contents, relationships, and structure. It emphasizes using `docgraph` specific tools over general text search
+(grep) to leverage the semantic structure of the graph.
+
+> [!TIP] Use this skill whenever you need to understand "how things are connected", "where a requirement is defined", or
+> "what is the impact of a change".
+
+## Exploration Tools
+
+### 1. `docgraph list` (Discovery)
+
+Use to find nodes matching a pattern or within a scope.
+
+- **Usage**: `docgraph list "<ID_PATTERN>"`
+- **Example**: `docgraph list "FR_LOGIN_*"`
+- **Benefit**: Quickly identifies relevant IDs without wading through raw file content.
+
+### 2. `docgraph type` (Structural Context)
+
+Use to understand the expected schema and constraints of a specific node type.
+
+- **Usage**: `docgraph type <TYPE>`
+- **Example**: `docgraph type FR`
+- **Benefit**: Reveals what sections and dependencies are mandatory or optional.
+
+### 3. `docgraph describe` (Deep Dive)
+
+Use to retrieve the full content and immediate relations of a specific node.
+
+- **Usage**: `docgraph describe <ID>`
+- **Example**: `docgraph describe FR_LOGIN_001`
+- **Benefit**: Provides a unified view of the node's text and its incoming/outgoing edges.
+
+### 4. `docgraph trace` (Impact & Lineage)
+
+Use to follow a chain of relationships (e.g., from requirement to code, or dependency tree).
+
+- **Usage**: `docgraph trace <START_ID> --direction <up|down>`
+- **Example**: `docgraph trace FR_LOGIN_001 --direction down`
+- **Benefit**: Visualizes the full path of derivation or satisfaction.
+
+### 6. Semantic Inference & Terminology Deduction (Cognitive Tool)
+
+Don't just look for matches; analyze how terms are used.
+
+- **Contextual Deduction**: If a term is used in multiple `FR` nodes related to "Auth", it likely refers to an
+  authentication concept.
+- **ID Mnemonics**: Use the prefix and mnemonic structure (e.g., `API-BILL-*`) to infer the scope of a term.
+- **Relational Meaning**: A node that "realizes" an `IF` (Interface) is likely an implementation detail (Module).
+
+### 5. `grep` (Keyword Fallback)
+
+Use only when you don't have a specific ID or node type to start with.
+
+- **Usage**: `grep -r "keyword" doc/`
+- **Benefit**: Finds mentions of terms that aren't formal IDs.
+
+---
+
+## Workflow Steps
+
+### 1. Intent Clarification
+
+Identify the core of the question:
+
+- **Structural**: "What is required for a Functional Requirement?" -> Use `type`.
+- **Existence**: "Do we have a requirement for SSO?" -> Use `list` or `grep`.
+- **Relationship**: "What modules implement the billing interface?" -> Use `describe` or `trace`.
+
+### 2. Multi-Layer Exploration
+
+Don't stop at the first finding. Follow the links:
+
+1. **Find** the starting node (`list`).
+2. **Understand** the starting node (`describe`).
+3. **Trace** the connections (`trace`) to see how it fits into the broader system.
+
+### 3. Contextual Synthesis & Inference
+
+Combine findings from the graph logic with the actual Markdown content.
+
+- Use `docgraph describe` to see the semantic links.
+- Use `view_file` to read the narrative context.
+- **Inference**: If a term is mentioned in the text but has no ID, search for related concepts using `list` or `grep` to
+  see if it's an alias or a broader system component.
+
+## Query Resolution Report
+
+When answering, structure your response as follows:
+
+### Findings Summary
+
+- **Primary Node(s)**: [ID(s) found]
+- **Key Relationships**: [e.g., "Satisfies ADR_001", "Realized by MOD_AUTH"]
+
+### Detailed Analysis
+
+Provide the detailed answer built from the gathered context.
+
+### Navigation Trace (optional)
+
+If relevant, show the path taken: `FR_001` -> `IF_001` -> `MOD_001`

docgraph-plugin/skills/impact/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: impact
+description:
+  Impact Analysis & Ripple Effect Assessment - Evaluate the consequences of adding or changing specifications.
+---
+
+# Impact Analysis & Ripple Effect Assessment
+
+This skill defines the process for analyzing the potential consequences of adding, modifying, or removing a
+specification node within the documentation graph. It leverages the graph's traceability to identify "ripple effects"
+across architectural layers (Requirements, Business, Architecture).
+
+> [!IMPORTANT] Impact analysis is mandatory before renaming IDs, moving files, or changing core requirement logic to
+> ensure the integrity of the entire graph.
+
+## Assessment Tools
+
+### 1. `docgraph describe` (Local Impact)
+
+Identify immediate connections to the node being changed.
+
+- **Goal**: List all direct inbound and outbound references.
+- **Workflow**: `docgraph describe <ID>` and inspect the "Relations" section.
+
+### 2. `docgraph trace` (Global Ripple Effect)
+
+Follow the chain of dependencies to the ends of the graph.
+
+- **Downward Trace**: `docgraph trace <ID> --direction down`
+  - _Identifies_: What modules (`MOD`), interfaces (`IF`), or sub-requirements are forced to change or re-validate.
+- **Upward Trace**: `docgraph trace <ID> --direction up`
+  - _Identifies_: What higher-level requirements (`FR`, `NFR`) or architectural decisions (`ADR`) might be affected or
+    lose their justification.
+
+### 3. `docgraph check` (Integrity Verification)
+
+Validate that the proposed change doesn't violate graph rules.
+
+- **Goal**: Detect broken links (`DG003`), template mismatches (`DG007`), or invalid reference directions (`DG006`).
+
+---
+
+## Analysis Workflow
+
+### 1. Identify Entry Point
+
+Define the specific node ID and the nature of the change (Add/Modify/Delete).
+
+### 2. Upward Impact (Dependencies/Justification)
+
+Analyze what this node "satisfies" or "derives from".
+
+- If this node is deleted, are the parent nodes still fully justified?
+- If this node is modified, does it still meet the parent's intent?
+
+### 3. Downward Impact (Satisfaction/Implementation)
+
+Analyze what "realizes" or "derives from" this node.
+
+- **Technical Impact**: Which Modules (`MOD`) or Interfaces (`IF`) need implementation changes?
+- **Specification Impact**: Are there child requirements that become obsolete or conflicting?
+
+### 4. Cross-Cutting Impact
+
+Check for associations with Cross-cutting Concepts (`CC`).
+
+- Does the change impact global system qualities like "Security" or "Performance"?
+
+---
+
+## Impact Assessment Report
+
+Structure your findings to provide a clear risk assessment:
+
+### Change Summary
+
+- **Target Node**: [ID]
+- **Action**: [Add / Modify / Delete]
+
+### Affected Nodes
+
+| Layer        | ID        | Impact Level | Description of Impact                                    |
+| :----------- | :-------- | :----------- | :------------------------------------------------------- |
+| Requirement  | `FR_...`  | HIGH/MED/LOW | e.g., "Parent requirement becomes partially unsatisfied" |
+| Architecture | `MOD_...` | HIGH/MED/LOW | e.g., "Requires logic change in billing handler"         |
+| Decision     | `ADR_...` | LOW          | e.g., "Remains consistent with ADR_001"                  |
+
+### Verification Status
+
+- **Result**: [CLEAN / ERRORS FOUND]
+- **Broken References**: [List of IDs or "None"]
+
+### Remediation Recommendation
+
+Propose steps to mitigate negative impacts (e.g., "Update `MOD_AUTH` to reflect the new interface").