NAF v4 Assistant - Convenience Functions

Overview

This assistant skill provides high-level convenience functions for NAF v4 / ADMBw modeling in Sparx Enterprise Architect. It acts as a productivity layer on top of the core NAF modeling skills, offering specialized utilities for common repetitive tasks.

Core Responsibilities

1. •Function Routing - Recognize which convenience function the user needs based on keywords and context
2. •Function Discovery - Help users discover available convenience functions
3. •Coordinator Integration - Route all NAF modeling operations through nafv4-coordinator
4. •Batch Processing - Handle multiple modeling operations efficiently

Architecture

The assistant follows a cascading skill architecture:

User Request
    ↓
nafv4-assistant (this skill)
    ↓
nafv4-coordinator
    ↓
Specialized NAF Skills:
  - nafv4-requirements
  - nafv4-architecture-metadata
  - nafv4-concepts
  - nafv4-logical-specification
  - nafv4-physical-resources
  - nafv4-service-specification

Exception: If the user explicitly mentions a specific NAF skill (e.g., "use nafv4-requirements"), the assistant can directly invoke that skill.

General Modeling Rules

These rules apply to all NAF v4 modeling tasks:

1. Modeling Target Clarification

When the modeling target is unclear, always ask the user where to model:

• •Currently open diagram - Add elements to the active diagram
• •Specific (non-displayed) diagram - Add to a named diagram that may not be open
• •Package in workspace - Create elements in a specific package location
• •New diagram - Create a new diagram first

Default behavior: If not explicitly specified, use the currently open diagram as the modeling target.

2. Element Existence Verification

Before using element names in any operation, especially when creating connections:

• •Always check first if the element already exists in the diagram or workspace
• •Use MCP find_elements_by_name to search for elements
• •If multiple elements with the same name exist, ask the user to clarify which one (by package path or GUID)
• •If the element doesn't exist, offer to create it or ask for clarification

This prevents:

• •Creating duplicate elements
• •Invalid connections to non-existent elements
• •Confusion about which element is being referenced

3. Automatic Diagram Layout

Never apply automatic diagram layout operations:

• •Do not use layout_diagram or similar automatic layout functions
• •Manual layout only - Let the user arrange elements manually in Sparx EA
• •Elements should be placed on diagrams using place_element_on_diagram, but their visual arrangement is left to the user
• •The user controls the visual organization of their diagrams

Available Convenience Functions

1. Requirement Naming

Function: Generate concise, information-rich titles for NAF v4 requirements from verbose descriptions.

Triggers:

• •Keywords: "requirement naming", "name requirements", "create titles", "short names"
• •Context: User provides list of requirement descriptions without names
• •Pattern: "create requirement with description: [long text]"

Load details: functions/requirement-naming.md

Usage Examples:

"I have 20 detailed requirement descriptions. Can you create short names for them?"
"Generate requirement titles for these functional requirements: [list]"
"Name these requirements: 1. The system shall..., 2. Users must be able to..."

See: Extended examples in references/extended_examples.md

[Future Functions]

Additional convenience functions will be added here as they are developed:

• •Batch Element Creation - Create multiple similar elements efficiently
• •Diagram Template Application - Apply standard diagram layouts
• •Traceability Matrix Generation - Generate requirement traceability reports
• •Model Validation - Check model completeness and consistency
• •Import/Export Helpers - Import requirements from Excel, export to documentation

Function Routing Logic

Automatic Detection

The assistant analyzes user requests for:

1. •

   Explicit function mention

   • •Example: "Use requirement naming for these descriptions"
   • •Action: Confirm with user, then activate function
2. •

   Keyword triggers

   • •Example: "Create short names for 15 requirements"
   • •Detected keywords: "short names", "requirements"
   • •Match: Requirement Naming function
   • •Action: Confirm detection, then activate
3. •

   Context pattern matching

   • •Example: User provides list of verbose requirement texts
   • •Detected pattern: Multiple long descriptions, likely needs naming
   • •Action: Ask user if requirement naming is needed
4. •

   No clear match

   • •Action: Present list of available functions and ask user to select

Confirmation Before Execution

When a function is detected (via keywords or pattern):

Assistant: "I've detected you might need the Requirement Naming function.
           Is that correct?

           This function will:
           - Analyze each requirement description
           - Generate concise 3-8 word titles
           - Preserve full descriptions in notes field

           Proceed with requirement naming?"

User: "Yes" / "No, I meant..."

Manual Function Selection

User can explicitly request to see available functions:

User: "What convenience functions do you offer?"
User: "Show me what the assistant can do"
User: "List available functions"

Response format:

Assistant: "NAF v4 Assistant - Available Convenience Functions:

1. **Requirement Naming**
   Generate concise titles from verbose requirement descriptions
   Use when: You have detailed requirements needing short names

2. [Future functions will appear here]

Which function would you like to use?"

Integration with NAF Coordinator

All modeling operations are routed through nafv4-coordinator, which then dispatches to specialized skills:

Available Skills

The assistant can work with these NAF v4 skills:

Coordinator:

• •nafv4-coordinator - Routes to specialized viewpoint skills, handles cross-viewpoint relationships

Specialized Viewpoint Skills:

• •nafv4-requirements - Requirements Viewpoints (R2-R6)
• •nafv4-architecture-metadata - Architecture Metadata Viewpoints (A1-A8, Ar)
• •nafv4-concepts - Concepts Viewpoints (C1-C8, Cr)
• •nafv4-logical-specification - Logical Specification Viewpoints (L1-L8, Lr)
• •nafv4-physical-resources - Physical Resource Specification Viewpoints (P1-P8, Pr)
• •nafv4-service-specification - Service Specification Viewpoints (S1-S8, Sr)

Standard Routing Pattern

User: "Create these 10 requirements with generated names: [list]"

↓ nafv4-assistant recognizes requirement naming need

Assistant (internal): Load functions/requirement-naming.md

↓ Generate titles using naming algorithm

Assistant (internal): Call nafv4-coordinator to create requirements

↓ nafv4-coordinator routes to nafv4-requirements

↓ nafv4-requirements creates requirement elements via MCP

↓ Result returned to user

Direct Skill Invocation

If user explicitly names a specific NAF skill:

User: "Use nafv4-requirements to add this functional requirement: [description]"

↓ nafv4-assistant detects explicit skill mention

↓ Directly invoke nafv4-requirements (skip nafv4-coordinator)

↓ nafv4-requirements handles the request

↓ Result returned to user

Workflow Examples

Example 1: Batch Requirement Creation with Naming

User Input:

"I have these 3 functional requirements that need short names:

1. The system shall provide the operator with the option to verify that
   the system has saved the new software settings.

2. All patient data must be encrypted using AES-256 encryption before
   transmission over the network.

3. The application shall respond to user queries within 2 seconds under
   normal load conditions."

Assistant Workflow:

1. •Detect function: Keywords "short names" + list of requirements → Requirement Naming
2. •Confirm: "I've detected you need requirement naming. Proceed?"
3. •Load function details: functions/requirement-naming.md
4. •Generate titles:
   • •FR-1: "Verify Settings Saved"
   • •FR-2: "Encrypt Patient Data AES-256"
   • •FR-3: "Query Response Time <2s"
5. •Route to coordinator: Request creation of 3 FunctionalRequirement elements
6. •Coordinator routes to nafv4-requirements
7. •Confirm to user:
   code

   Created 3 functional requirements:
   1. "Verify Settings Saved"
   2. "Encrypt Patient Data AES-256"
   3. "Query Response Time <2s"
   
   Full descriptions preserved in notes field.
   

Example 2: Function Discovery

User Input:

"What can the assistant do?"

Assistant Response:

NAF v4 Assistant - Available Convenience Functions:

1. **Requirement Naming**
   Generate concise, information-rich titles from verbose requirement descriptions

   Typical use: "I have 20 requirements needing short names"
   Triggers: "requirement naming", "create titles", "short names"

[Future functions listed here as added]

Would you like to use any of these functions?

Example 3: Ambiguous Request

User Input:

"Help me with these requirements: [list of 5 detailed descriptions]"

Assistant Response:

I see you have 5 requirement descriptions. Which function would help you?

1. **Requirement Naming** - Generate short titles for these requirements
2. **Create Requirements** - Add these to your NAF model (via coordinator)
3. **Both** - Generate names AND create in model

Which would you like?

Progressive Data Loading

Always in context:

• •Core routing logic (this SKILL.md)
• •Available functions list
• •Integration patterns

Load on demand:

• •functions/requirement-naming.md - When requirement naming is needed
• •references/extended_examples.md - When user needs examples or edge cases
• •[Future function files] - As additional functions are developed

This keeps the skill efficient while providing access to detailed algorithms when needed.

Best Practices

For Users

1. •

   Be explicit when possible

   • •Good: "Use requirement naming for these 10 descriptions"
   • •Okay: "Create short names for these requirements"
   • •Vague: "Help with these" (assistant will ask for clarification)
2. •

   Provide context

   • •If working on a specific diagram, mention it
   • •If targeting a specific package, specify it
   • •If using organizational naming conventions, state them
3. •

   Batch operations are efficient

   • •Process multiple requirements at once
   • •Assistant handles iteration internally
4. •

   Review generated output

   • •Titles are algorithmically generated
   • •Review for accuracy and consistency
   • •Request adjustments if needed

For the Assistant (Internal Guidelines)

1. •

   Always confirm before execution

   • •Especially for batch operations
   • •Show what will be done before doing it
2. •

   Load function details only when needed

   • •Keep initial response fast
   • •Load detailed algorithms on demand
3. •

   Route through coordinator by default

   • •Exception: Explicit skill mention
   • •Coordinator handles cross-viewpoint complexity
4. •

   Preserve user intent

   • •Keep full descriptions in notes
   • •Generated names supplement, don't replace

Error Handling

Function Not Recognized

User: "Create widget names for these items"