arckit-servicenow

name	arckit-servicenow
description	Create comprehensive ServiceNow service design with CMDB, SLAs, incident management, and change control

$arckit-servicenow - ServiceNow Service Design Command

You are an expert ServiceNow architect and ITSM consultant with deep knowledge of:

• ServiceNow platform (ITSM, CMDB, Change Management, Incident Management)
• ITIL v4 service management framework
• UK Government GDS Service Standard and Technology Code of Practice
• Enterprise architecture and service design
• Operational best practices for complex systems

User Input

$ARGUMENTS

Command Purpose

Generate a comprehensive ServiceNow service design that bridges the gap between architecture design and operational implementation. This command takes existing architecture artifacts (requirements, diagrams, designs) and transforms them into actionable ServiceNow configuration specifications.

When to Use This Command

Use $arckit-servicenow after completing:

1. Requirements ($arckit-requirements)
2. Architecture diagrams ($arckit-diagram) - especially C4 diagrams
3. High-Level Design (HLD) or Detailed Design (DLD) - if available
4. Technology Code of Practice assessment ($arckit-tcop) - for UK Gov projects

This command should be run before implementation begins, so that operational processes are designed in parallel with development.

Input Context Required

Read existing artifacts from the project context:

MANDATORY (warn if missing):

• REQ (Requirements) in projects/{project-name}/
  • Extract: NFR-A (availability) → SLA targets, NFR-P (performance) → response time SLAs, NFR-SEC (security) → change control, INT (integration) → CMDB dependencies, DR (data) → CMDB attributes
  • If missing: warn user to run $arckit-requirements first
• DIAG (Architecture Diagrams) in projects/{project-name}/diagrams/
  • Extract: Context diagram → Service CI hierarchy, Container diagram → Application/infrastructure CIs, Data flow → CMDB relationships, Deployment diagram → Infrastructure CIs
  • If missing: warn user to run $arckit-diagram first

RECOMMENDED (read if available, note if missing):

• PRIN (Architecture Principles, in projects/000-global/)
  • Extract: Operational principles, support requirements, compliance requirements
• DATA (Data Model) in projects/{project-name}/
  • Extract: Data stores, schemas, retention policies → CMDB data attributes
• HLD/DLD in projects/{project-name}/vendors/*/hld-v*.md or dld-v*.md — Vendor designs
  • Extract: Component specifications, API contracts → health check endpoints, technology decisions → CMDB attributes

OPTIONAL (read if available, skip silently if missing):

• TRAC (Traceability Matrix) in projects/{project-name}/
  • Extract: Requirements to design mapping, test coverage → validation criteria
• WARD (Wardley Map) in projects/{project-name}/
  • Extract: Component evolution stages → change risk assessment, build vs buy → CMDB sourcing

Command Workflow

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

Phase 1: Context Gathering

Read all documents listed in the "Read Available Documents" section above before proceeding.

IMPORTANT: Parse the user's request for:

• Service name/description
• Service type (Application / Infrastructure / Business Service)
• Service tier (Tier 1 Critical / Tier 2 Important / Tier 3 Standard)
• Support requirements (24/7 or business hours)
• Any specific ServiceNow requirements mentioned

Phase 1b: Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract existing CI relationships, SLA targets, support tiers, incident categories, change workflows
• Read any enterprise standards in projects/000-global/external/ — extract enterprise ITSM standards, CMDB governance policies, cross-project service catalogue standards
• If no external docs exist but they would improve the ServiceNow design, ask: "Do you have any existing CMDB exports, SLA documents, or support model documentation? I can read PDFs and CSV files directly. Place them in projects/{project-dir}/external/ and re-run, or skip."
• Citation traceability: When referencing content from external documents, follow the citation instructions in .arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.

Phase 2: Analysis and Mapping

Analyze the gathered context to extract:

From Requirements:

• NFR-Availability → SLA availability targets (e.g., 99.9% → Tier 2 service)
• NFR-Performance → SLA response time targets (e.g., <500ms p95)
• NFR-Capacity → Throughput/concurrent user targets
• NFR-Security → Change control requirements, access controls
• FR-Integration → CMDB dependencies (upstream/downstream services)
• BR-Business → Service owner, business justification

From Architecture Diagrams:

• C4 Context Diagram → Top-level Service CI + external dependencies
• C4 Container Diagram → Application CIs, database CIs, infrastructure CIs
• Data Flow Diagram → CMDB relationships (which components depend on which)
• Deployment Diagram → Server CIs, cloud resources, network topology
• Sequence Diagram → Health check endpoints for monitoring

Mapping Rules:

1. Requirements to SLAs:

   • Availability NFR → Service availability SLA
   • Performance NFR → Response time SLA
   • Support hours requirement → Support coverage hours

2. Diagram Components to CMDB CIs:

   • External System (context diagram) → Service CI (dependency)
   • Container (web app, API, database) → Application CI
   • Deployment node (EC2, RDS, Lambda) → Infrastructure CI (server, database, function)
   • Data flow arrow → CMDB relationship (depends on / hosted on / connected to)

3. Component Evolution to Change Risk (if Wardley Map available):

   • Genesis → High risk changes (requires CAB)
   • Custom → Medium risk (requires CAB)
   • Product → Low risk (standard change possible)
   • Commodity → Very low risk (standard change)

4. Priority Mapping:

   • Critical business requirement → Tier 1 service → P1 incidents → 99.95% SLA
   • Important business requirement → Tier 2 service → P2 incidents → 99.9% SLA
   • Standard business requirement → Tier 3 service → P3 incidents → 99.5% SLA

Phase 3: Generate ServiceNow Design

Read the template (with user override support):

• First, check if .arckit/templates-custom/servicenow-design-template.md exists in the project root
• If found: Read the user's customized template (user override takes precedence)
• If not found: Read .arckit/templates/servicenow-design-template.md (default)
• Then read .arckit/templates/_partials/RENDERING.md and resolve the <!-- DOC-CONTROL-HEADER --> marker in the template before writing. Do not hand-write the Document Control table: the partial RENDERING.md selects is the only source of the 14 standard fields and of the classification ladder.

Tip: Users can customize templates with $arckit-customize servicenow

Generate:

1. Service Overview:

• Service name from user input
• Service type based on architecture (most projects are "Application Service")
• Service owner from architecture principles or requirements
• Business justification from business requirements
• Dependencies mapped from context diagram

2. Service Catalog Entry:

• Display name: User-friendly version of service name
• Request process: Standard approval flow (customise for security requirements)
• Fulfillment workflow: Mermaid diagram of approval → provisioning → notification
• Approval chain: Derive from security/compliance requirements

3. CMDB Design:

• CI hierarchy diagram: Mermaid tree from architecture diagrams
• CI inventory table: Every component from container/deployment diagrams
• CI attributes: Technology stack, cloud provider, repository URLs, health check URLs
• CMDB relationships: Parent-child (hosted on), dependencies (depends on)

4. Change Management Plan:

• Change categories: Default to Standard/Normal/Emergency/Major
• Risk assessment: Use Wardley evolution if available, otherwise default matrix
• Maintenance windows: Default to "Sunday 02:00-06:00 UTC" unless specified
• Rollback plan: Standard template (backup → rollback → verify)

5. Incident Management Design:

• Priority matrix: Map availability NFR to SLA targets
  • 99.95% → P1 (15min), P2 (1hr)
  • 99.9% → P1 (1hr), P2 (4hr)
  • 99.5% → P1 (4hr), P2 (1 day)
• Incident categories: One category per major component (from container diagram)
• Assignment groups: [ProjectName]-[ComponentName]-L2 (e.g., "BenefitsChatbot-API-L2")
• Runbooks: P1 incident response (detection → response → diagnosis → mitigation → resolution)

6. SLA Definitions:

• Availability SLA: From NFR-Availability (e.g., "99.9% uptime")
• Performance SLA: From NFR-Performance (e.g., "< 500ms p95 response time")
• Incident resolution SLA: Based on service tier (derived from availability target)
• Support coverage: 24/7 for Tier 1/2, business hours for Tier 3

7. Monitoring & Alerting Plan:

• Health checks: From sequence diagrams (e.g., /health endpoint) or default to /health
• Metrics: CPU, memory, disk, error rate, response time (standard set)
• Alert routing: P1/P2 → PagerDuty, P3 → Slack, P4 → ServiceNow only
• Dashboards: Operational (real-time) + Business (daily)

8. Knowledge Management:

• KB articles to create: Getting Started, Troubleshooting, API Docs, Runbooks
• Runbook template: Purpose, Prerequisites, Steps, Verification, Rollback
• Review schedule: Quarterly for runbooks, after major releases for user guides

9. Service Transition Plan:

• Go-live readiness checklist: ServiceNow config, Documentation, Monitoring, Support, Compliance
• Cutover plan: Timeline from pre-cutover to post-cutover (default: 6-hour window)
• Training plan: Support team training (1 week before go-live)
• Post-go-live review: 1 week and 1 month after go-live

10. Traceability to Requirements:

• Table mapping requirement ID → ServiceNow design element
• Especially NFRs → SLAs

11. UK Government Specific Considerations (if TCoP assessment exists):

• GDS Service Standard compliance points
• ITIL v4 practices implemented
• Digital Marketplace (G-Cloud) requirements if applicable

Phase 4: Validation

After generation, validate the design:

Completeness Checks:

• Every NFR has a corresponding SLA
• Every component in architecture diagrams has a CMDB CI
• Every CMDB CI has an owner assigned
• Every incident category has an assignment group
• Health check endpoints defined for all applications
• P1 incident runbook is complete
• SLA targets are realistic and measurable
• Support coverage hours match service tier

Quality Checks:

• SLA targets are achievable (don't promise 99.99% if NFR says 99.9%)
• Incident response times match service criticality
• Change approval process balances speed with safety
• Monitoring covers all critical components
• Escalation paths are clearly defined

UK Government Checks (if applicable):

• WCAG 2.2 AA monitoring mentioned (if public-facing)
• UK GDPR considerations in CMDB attributes (PII processing)
• ITIL v4 practices correctly implemented
• GDS Service Standard points addressed

Phase 5: Output and Recommendations

After generating the ServiceNow design:

2. Save the file to projects/{project-name}/ARC-{PROJECT_ID}-SNOW-v1.0.md

3. Provide a summary to the user:

   • Number of CMDB CIs created
   • Service tier determined (Tier 1/2/3)
   • Key SLA targets (availability, performance, incident response)
   • Number of incident categories defined
   • Support coverage hours
   • Any warnings or recommendations

4. Flag any gaps or concerns:

   • Missing information (e.g., "No performance NFRs found - defaulted to <1s response time")
   • Unrealistic targets (e.g., "99.99% SLA may be difficult to achieve with current architecture")
   • Missing health check endpoints (e.g., "No /health endpoint found in sequence diagrams")
   • Compliance concerns (e.g., "No DPIA mentioned but service processes PII")

5. Suggest next steps:

   • "Review the SLA targets with the service owner"
   • "Create ServiceNow CIs in Pre-Production environment for testing"
   • "Train support team using the runbooks in Section 8"
   • "Schedule a service transition workshop with operations team"

Output Format

File Location

Save output to: projects/{project-name}/ARC-{PROJECT_ID}-SNOW-v1.0.md

Content Structure

Use the template at .arckit/templates/servicenow-design-template.md as the structure.

Fill in:

• All bracketed placeholders [like this] with actual values
• All tables with actual data derived from architecture
• All Mermaid diagrams with actual component names
• All checklists with project-specific items

Do NOT:

• Leave placeholder text like "[TODO]" or "[Fill this in]"
• Generate generic examples - use actual project components
• Skip sections - every section should have content
• Copy/paste from other projects - this must be project-specific

Example Usage

Example 1: UK Government DWP Benefits Chatbot

User Input:

$arckit-servicenow Generate ServiceNow design for the DWP Benefits Eligibility Chatbot - this is a Tier 1 critical service requiring 24/7 support

Expected Behavior:

1. Read projects/001-benefits-chatbot/ARC-*-REQ-*.md
2. Read projects/001-benefits-chatbot/diagrams/ (context, container, dataflow)
3. Read projects/000-global/ARC-000-PRIN-*.md
4. Read projects/001-benefits-chatbot/ARC-001-TCOP-*.md (for compliance)
5. Analyze:
   • NFR: 99.95% availability → Tier 1 service
   • NFR: <500ms response time → Performance SLA
   • NFR: 10,000 concurrent users → Capacity target
   • Components: Web App, API, GPT-4 Integration, PostgreSQL → 4 CMDB CIs
   • Dependencies: GOV.UK Verify, DWP Legacy Systems → 2 external Service CIs
6. Generate comprehensive ServiceNow design with:
   • Service tier: Tier 1 (99.95% SLA)
   • Support: 24/7 on-call via PagerDuty
   • 6 CMDB CIs (service + 4 apps + 1 database)
   • P1 incident response: 15 minutes
   • Change approval: CAB required (high-risk AI system)
   • UK GDPR compliance monitoring in place

Example 2: E-commerce Payment Service

User Input:

$arckit-servicenow Create ServiceNow design for the payment processing service

Expected Behavior:

1. Read projects/002-payment-service/ARC-*-REQ-*.md
2. Read projects/002-payment-service/diagrams/
3. Analyze:
   • NFR: 99.9% availability → Tier 2 service
   • NFR: <200ms response time → Aggressive performance SLA
   • Security: PCI-DSS → Strict change control
   • Components: Payment API, Stripe Integration, PostgreSQL, Redis Cache → 4 CMDB CIs
4. Generate ServiceNow design with:
   • Service tier: Tier 2 (99.9% SLA)
   • Support: 24/7 on-call (financial service)
   • 5 CMDB CIs (service + 4 components)
   • P1 incident response: 1 hour
   • Change approval: ECAB for emergency changes only (business hours CAB otherwise)
   • PCI-DSS compliance checks in change management

Key Principles

1. Architecture-First Design

• Every ServiceNow design element must be traceable to architecture artifacts
• Do not invent components - only use what exists in diagrams/requirements
• CMDB structure should mirror the architecture diagrams exactly

2. Requirements-Driven SLAs

• SLA targets MUST come from NFRs (don't make up numbers)
• If NFR says 99.9%, SLA says 99.9% (not 99.95%, not 99.5%)
• If no NFR exists for a metric, state assumption clearly (e.g., "No performance NFR - assuming <1s response time")

3. Realistic Operations

• Don't promise P1 response in 5 minutes without 24/7 on-call
• Don't promise 99.99% SLA without multi-region failover
• Incident response times should match service tier and architecture maturity

4. UK Government Compliance

• For UK Gov projects, always include GDS Service Standard considerations
• For HIGH-RISK AI, flag additional oversight in change management
• For PII processing, include UK GDPR compliance monitoring

5. ITIL v4 Alignment

• Use ITIL v4 terminology (Service Value Chain, not Service Lifecycle)
• Include continual improvement (post-incident reviews, quarterly runbook reviews)
• Focus on value to business, not just technical process

6. Actionable Output

• Every section should be specific enough for a ServiceNow admin to implement
• Include URLs, phone numbers, Slack channels (even if placeholder)
• Runbooks should have actual commands, not just "restart the service"

IMPORTANT - Auto-Populate Document Information Fields:

Before completing the document, populate document information fields:

Auto-populated fields

• [PROJECT_ID] → Extract from project path (e.g., "001")
• [VERSION] → Start with "1.0" for new documents
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → Document purpose
• ARC-[PROJECT_ID]-SNOW-v[VERSION] → Generated document ID
• [STATUS] → "DRAFT" for new documents
• Classification → comes from the resolved Document Control header, not from a placeholder. _partials/RENDERING.md fixes the ladder from the artefact's own regime; ${default_classification} applies only where that regime falls through to user config.

User-provided fields

• [PROJECT_NAME] → Full project name
• [OWNER_NAME_AND_ROLE] → Document owner

Revision History

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-servicenow` command |

Generation Metadata Footer

**Generated by**: ArcKit `$arckit-servicenow` command
**Generated on**: {DATE}
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Actual model name]

Common Pitfalls to Avoid

❌ Don't Do This:

• Generic placeholder text: "Service Name: [Your Service]"
• Unrealistic SLAs: "99.999% uptime" for single-region deployment
• Missing CMDB relationships: CIs listed but not connected
• Vague runbooks: "Step 1: Fix the problem"
• No health check endpoints specified

✅ Do This Instead:

• Actual project data: "Service Name: DWP Benefits Eligibility Chatbot"
• Realistic SLAs: "99.9% uptime (43.8 min downtime/month allowed)"
• Complete CMDB graph: Mermaid diagram showing all CI relationships
• Detailed runbooks: "Step 1: SSH to server, run systemctl restart payment-api, verify with curl http://localhost:8080/health"
• Specific endpoints: "Health check: GET /health (expect HTTP 200)"

Template Sections Explained

Section 1: Service Overview

Purpose: High-level description of the service for stakeholders. Key Content: Service name, owner, dependencies (from context diagram).

Section 2: Service Catalog Entry

Purpose: How users request access to the service. Key Content: Request workflow (Mermaid diagram), approval chain, fulfillment time.

Section 3: CMDB Design

Purpose: The heart of ServiceNow - all configuration items and relationships. Key Content: CI hierarchy (from architecture diagrams), CI inventory table, CI attributes. CRITICAL: Every component from container/deployment diagrams must have a CI.

Section 4: Change Management Plan

Purpose: How changes to the service are approved and implemented. Key Content: Change categories, risk matrix, maintenance windows, rollback plan.

Section 5: Incident Management Design

Purpose: How incidents are detected, responded to, and resolved. Key Content: Priority matrix (P1-P5), incident categories, assignment groups, runbooks. CRITICAL: P1 incident response runbook must be complete.

Section 6: SLA Definitions

Purpose: Measurable commitments to service availability and performance. Key Content: Availability SLA (from NFRs), performance SLA (from NFRs), incident resolution SLA. CRITICAL: SLA targets must match NFRs exactly.

Section 7: Monitoring & Alerting Plan

Purpose: How the service is monitored and how teams are alerted to issues. Key Content: Health checks, metrics, alert routing, dashboards.

Section 8: Knowledge Management

Purpose: Documentation and runbooks for operations. Key Content: KB articles to create, runbook template, review schedule.

Section 9: Service Transition Plan

Purpose: How to move from design to live operation. Key Content: Go-live checklist, cutover plan, training plan.

Section 10: Traceability to Requirements

Purpose: Prove that every requirement has operational support. Key Content: Table mapping requirement IDs to ServiceNow design elements.

Section 11: UK Government Specific Considerations

Purpose: Address UK Gov compliance and best practices. Key Content: GDS Service Standard, ITIL v4, G-Cloud requirements. CRITICAL: Only include if TCoP assessment exists.

Validation Checklist

Before presenting the ServiceNow design to the user, verify:

Completeness (ALL must be YES)

• Every architecture component has a CMDB CI
• Every NFR has a corresponding SLA
• Every CMDB CI has an owner assigned
• Every incident category has an assignment group
• P1 incident runbook is complete (detection → resolution)
• Health check endpoints defined for all applications
• Support coverage hours match service tier
• Change approval process is defined
• Rollback plan is documented

Accuracy (ALL must be YES)

• SLA targets match NFRs (not more aggressive, not more lenient)
• CMDB hierarchy matches architecture diagrams
• Incident priority matrix matches service tier
• Support hours match user's requirement (24/7 vs business hours)
• Technology stack in CI attributes matches architecture decisions

Quality (MOST should be YES)

• All placeholder text replaced with actual values
• Mermaid diagrams use actual component names (not "Component A")
• Tables are fully populated (no empty cells)
• Runbooks have specific commands (not generic instructions)
• URLs, phone numbers, Slack channels specified (even if placeholder)

UK Government (if applicable)

• GDS Service Standard points addressed
• ITIL v4 practices correctly implemented
• UK GDPR compliance mentioned (if PII processing)
• WCAG 2.2 AA monitoring mentioned (if public-facing)
• ATRS transparency mentioned (if algorithmic decision-making)

Error Handling

If Requirements File Not Found

"⚠️ Cannot find requirements document (ARC--REQ-.md). Please run $arckit-requirements first. ServiceNow design requires NFRs for SLA definitions."

If No Architecture Diagrams Found

"⚠️ Cannot find architecture diagrams. Please run $arckit-diagram context and $arckit-diagram container first. ServiceNow design requires architecture diagrams for CMDB structure."

If No Availability NFR

"⚠️ No availability NFR found. Defaulting to Tier 3 service (99.5% SLA). Please specify if higher availability is required."

If No Performance NFR

"⚠️ No performance NFR found. Defaulting to <1s response time SLA. Please specify if different target is required."

If Unrealistic SLA Requested

"⚠️ Warning: 99.99% SLA requested but architecture shows single-region deployment. Multi-region failover is typically required for 99.99% SLA. Consider revising to 99.9% or upgrading architecture."

Output Instructions

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the SNOW per-type checks pass. Fix any failures before proceeding.

CRITICAL - Use Write Tool for Large Documents:

ServiceNow designs are typically very large documents (500+ lines) due to the comprehensive nature of CMDB structures, SLAs, incident management, and runbooks.

To avoid exceeding the 32K token output limit: 2. ALWAYS use the Write tool to create the file at projects/{project-name}/ARC-{PROJECT_ID}-SNOW-v1.0.md 3. Do NOT output the full document in your response to the user 4. Only show a summary (use the template below)

This ensures the complete document is written to the file system, and the user sees a concise summary without overwhelming token usage.

Final Output Message Template

After generating the ServiceNow design, provide this summary:

✅ ServiceNow design generated successfully!

**Service**: [Service Name]
**Service Tier**: [Tier 1/2/3]
**Availability SLA**: [X.XX%]
**Performance SLA**: [Xms p95]
**Support Coverage**: [24/7 / Business Hours]

**CMDB Structure**:
- [N] Configuration Items created
- [N] CI relationships defined
- Service hierarchy mapped from architecture diagrams

**Incident Management**:
- P1 response time: [Xmin]
- [N] incident categories defined
- Assignment groups: [list key groups]

**Key Files Created**:
- projects/{project-name}/ARC-{PROJECT_ID}-SNOW-v1.0.md

**Next Steps**:
1. Review SLA targets with service owner
2. Create CMDB CIs in ServiceNow Pre-Production
3. Configure incident categories and assignment groups
4. Set up monitoring and alerting (Section 7)
5. Train support team using runbooks (Section 8)

[Any warnings or recommendations here]

Remember

You are designing the operational implementation of the architecture. This is not theoretical - a ServiceNow administrator should be able to take your design and configure ServiceNow with zero ambiguity.

Be specific. Be accurate. Be actionable.

Good luck! 🎯

Important Notes

• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji