arckit-requirements

name	arckit-requirements
description	Create comprehensive business and technical requirements

You are helping an enterprise architect define comprehensive requirements for a project that will be used for vendor RFPs and architecture reviews.

User Input

$ARGUMENTS

Instructions

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.

1. Identify the target project:

   • Use the ArcKit Project Context (above) to find the project matching the user's input (by name or number)
   • If no match, create a new project:
     1. Use Glob to list projects/*/ directories and find the highest NNN-* number (or start at 001 if none exist)
     2. Calculate the next number (zero-padded to 3 digits, e.g., 002)
     3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
     4. Use the Write tool to create projects/{NNN}-{slug}/README.md with the project name, ID, and date — the Write tool will create all parent directories automatically
     5. Also create projects/{NNN}-{slug}/external/README.md with a note to place external reference documents here
     6. Set PROJECT_ID = the 3-digit number, PROJECT_PATH = the new directory path

2. Read existing artifacts from the project context:

   MANDATORY (warn if missing):

   • STKE (Stakeholder Analysis) — Extract: goals, priorities, drivers, conflict analysis, RACI matrix
     • If missing: warn user to run $arckit-stakeholders first

   RECOMMENDED (read if available, note if missing):

   • PRIN (Architecture Principles, in 000-global) — Extract: technology standards, constraints, compliance requirements for NFR alignment
     • If missing: suggest running $arckit-principles first
   • RISK (Risk Register) — Extract: risk-driven requirements, mitigations that need NFRs
   • SOBC (Business Case) — Extract: benefits, cost constraints, ROI targets for BR alignment

   OPTIONAL (read if available, skip silently):

   • PLAN (Project Plan) — Extract: timeline constraints, phasing for requirement prioritization

3. Read external documents and policies:

   • Read any external documents listed in the project context (external/ files) — extract requirements, constraints, scope definitions, acceptance criteria, legacy system interfaces
   • Read any global policies listed in the project context (000-global/policies/) — extract mandatory compliance requirements, technology constraints, security standards
   • Read any enterprise standards in projects/000-global/external/ — extract cross-project requirements patterns
   • If no external docs exist but they would significantly improve requirements, ask: "Do you have any RFP/ITT documents, legacy system specifications, or user research reports? I can read PDFs and Word docs 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.

4. Read the template (with user override support):

   • First, check if .arckit/templates-custom/requirements-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/requirements-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.
   • Update Template Version: Replace the version in the template metadata line with {ARCKIT_VERSION} from the session context

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

5. Generate comprehensive requirements based on user input:

   Business Requirements (BR-xxx):

   • Business objectives and success criteria
   • ROI and cost savings expectations
   • Timeline and milestones
   • Stakeholder needs

   Functional Requirements (FR-xxx):

   • User personas and their needs
   • User stories and use cases
   • Features and capabilities
   • User workflows

   Non-Functional Requirements (NFR-xxx):

   • Performance (response time, throughput, concurrent users)
   • Security (authentication, authorisation, encryption, compliance)
   • Scalability (growth projections, load handling)
   • Reliability (uptime SLA, MTBF, MTTR)
   • Compliance (regulations, standards, certifications)

   Integration Requirements (INT-xxx):

   • Upstream/downstream systems
   • APIs and protocols
   • Data exchange formats
   • Authentication methods

   Data Requirements (DR-xxx):

   • Data models and schemas
   • Data retention and archival
   • Data privacy and classification
   • Migration requirements

6. Ensure traceability: Each requirement MUST have:

   • Unique ID (BR-001, FR-001, NFR-P-001, etc.)
   • Clear requirement statement
   • Acceptance criteria (testable)
   • Priority (MUST/SHOULD/MAY)
   • Rationale

7. Align with stakeholder goals and architecture principles:

   • If stakeholder analysis exists, trace requirements back to stakeholder goals:
     • Example: "BR-001 addresses CFO's goal G-1: Reduce infrastructure costs 40% by end of Year 1"
     • Example: "NFR-P-001 supports Operations Director's outcome O-3: Maintain 99.95% uptime"
   • Reference relevant principles from projects/000-global/ARC-000-PRIN-*.md:
     • Example: "NFR-S-001 aligns with Security by Design principle (SEC-001)"
   • Ensure high-priority stakeholder drivers get MUST requirements
   • Document which stakeholder benefits from each requirement

8. Identify and resolve conflicting requirements:

   • Review stakeholder analysis conflict analysis section for known competing drivers
   • Identify requirement conflicts that arise from stakeholder conflicts:
     • Speed vs Quality: CFO wants fast delivery vs Operations wants thorough testing
     • Cost vs Features: Finance wants minimal spend vs Product wants rich features
     • Security vs Usability: Security wants MFA vs Users want seamless experience
     • Flexibility vs Standardization: Business wants customization vs IT wants standards
   • For each conflict, document:
     • Conflicting Requirements: Which requirements are incompatible (e.g., FR-001 vs NFR-P-002)
     • Stakeholders Involved: Who wants what (e.g., CFO wants X, CTO wants Y)
     • Trade-off Analysis: What is gained and lost with each option
     • Resolution Strategy: How will this be resolved:
       • Prioritize: Choose one over the other based on stakeholder power/importance
       • Compromise: Find middle ground (e.g., MFA for admin, passwordless for regular users)
       • Phase: Satisfy both but at different times (e.g., MVP focused on speed, Phase 2 adds quality)
       • Innovate: Find creative solution that satisfies both (e.g., automated testing for speed AND quality)
   • Decision Authority: Reference stakeholder analysis RACI matrix for who decides
   • Document Resolution: Create explicit "Requirement Conflicts & Resolutions" section showing:
     • What was chosen and why
     • What was deferred or rejected
     • Which stakeholder "won" and which "lost"
     • How losing stakeholder will be managed (communication, future consideration)
   • Transparency: Be explicit about trade-offs - don't hide conflicts or pretend both can be satisfied

9. Write the output:

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

   • CRITICAL - Token Efficiency: Use the Write tool to create projects/{project-dir}/ARC-{PROJECT_ID}-REQ-v${VERSION}.md
   • DO NOT output the full document in your response (this exceeds 32K token limit!)
   • Use the exact template structure
   • Include all sections even if some are TBD
   • MUST include "Requirement Conflicts & Resolutions" section if any conflicts exist

CRITICAL - Auto-Populate Document Control Fields:

Before completing the document, populate ALL document control fields in the header:

Step 0: Detect Version

Before generating the document ID, check if a previous version exists:

1. Look for existing ARC-{PROJECT_ID}-REQ-v*.md files in the project directory
2. If no existing file: Use VERSION="1.0"
3. If existing file found:
   • Read the existing document to understand its scope
   • Compare against current inputs and requirements
   • Minor increment (e.g., 1.0 → 1.1): Scope unchanged — refreshed content, updated details, corrections
   • Major increment (e.g., 1.0 → 2.0): Scope materially changed — new requirement categories, removed categories, significant new requirements added
4. Use the determined version for document ID, filename, Document Control, and Revision History
5. For v1.1+/v2.0+: Add a Revision History entry

Step 1: Construct Document ID

• Document ID: ARC-{PROJECT_ID}-REQ-v{VERSION} (e.g., ARC-001-REQ-v1.0)

Step 2: Populate Required Fields

Auto-populated fields (populate these automatically):

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → Determined version from Step 0
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → "Business and Technical Requirements"
• ARC-[PROJECT_ID]-REQ-v[VERSION] → Construct using format from Step 1
• [COMMAND] → "arckit.requirements"

User-provided fields (extract from project metadata or user input):

• [PROJECT_NAME] → Full project name from project metadata or user input
• [OWNER_NAME_AND_ROLE] → Document owner (prompt user if not in metadata)
• 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.

Calculated fields:

• [YYYY-MM-DD] for Next Review Date → Current date + 30 days (requirements, research, risks)
• [YYYY-MM-DD] for Next Review Date → Phase gate dates (Alpha/Beta/Live for compliance docs)

Pending fields (leave as [PENDING] until manually updated):

• [REVIEWER_NAME] → [PENDING]
• [APPROVER_NAME] → [PENDING]
• [DISTRIBUTION_LIST] → Default to "Project Team, Architecture Team" or [PENDING]

Step 3: Populate Revision History

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-requirements` command | [PENDING] | [PENDING] |

Step 4: Populate Generation Metadata Footer

The footer should be populated with:

**Generated by**: ArcKit `$arckit-requirements` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "Claude Sonnet 5 (session default)"]
**Generation Context**: [Brief note about source documents used]

Example Rendered Header and Revision History

## Document Control

<!-- DOC-CONTROL-HEADER -->
<!-- Resolved at command-execution time per _partials/RENDERING.md. -->

## Revision History

| Version | Date | Author | Changes | Approved By | Approval Date |
|---------|------|--------|---------|-------------|---------------|
| 1.0 | 2025-10-29 | ArcKit AI | Initial creation from `$arckit-requirements` command | [PENDING] | [PENDING] |

10. Show summary only (NOT the full document):

After writing the file with Write tool, show ONLY this summary:

## Requirements Complete ✅

**Project**: [Project Name]
**File Created**: `projects/[PROJECT]/ARC-{PROJECT_ID}-REQ-v1.0.md`

### Requirements Summary

**Total Requirements**: [Number]
- Business Requirements (BR-xxx): [Number]
- Functional Requirements (FR-xxx): [Number]
- Non-Functional Requirements (NFR-xxx): [Number]
  - Performance (NFR-P-xxx): [Number]
  - Security (NFR-SEC-xxx): [Number]
  - Scalability (NFR-S-xxx): [Number]
  - Availability (NFR-A-xxx): [Number]
  - Compliance (NFR-C-xxx): [Number]
- Data Requirements (DR-xxx): [Number]
- Integration Requirements (INT-xxx): [Number]

**Requirement Conflicts**: [Number] conflicts identified and resolved
- [Brief summary of key conflicts and resolutions]
- [Which stakeholders won/lost in conflicts]

**Compliance Requirements**:
- [List key compliance frameworks: PCI-DSS, GDPR, HIPAA, etc.]

**Key Gaps/TBDs**:
- [List any major gaps that need follow-up]

### What's in the Document

- Business Requirements with measurable success criteria
- Functional Requirements organized by user journey
- Non-Functional Requirements with specific targets
- Data Requirements with GDPR considerations
- Integration Requirements with third-party systems
- Acceptance Criteria for each requirement
- Requirements Traceability Matrix
- Requirement Conflicts & Resolutions

### Next Steps

- Review `ARC-{PROJECT_ID}-REQ-v1.0.md` for full details
- [If DR-xxx exist]: Run `$arckit-data-model` to create comprehensive data model
 [If no DR-xxx]: Run  to research technology options

Example Usage

User: $arckit-requirements Create requirements for a payment gateway modernization project

You should:

• Check for architecture principles
• Create project "payment-gateway-modernization" (gets number 001)
• Generate comprehensive requirements:
  • Business: Cost savings, improved conversion, reduced downtime
  • Functional: Payment processing, refunds, fraud detection, reporting
  • NFR: PCI-DSS compliance, 99.99% uptime, <2s response time, encryption
  • Integration: CRM, accounting system, fraud service
  • Data: Transaction records, PII handling, 7-year retention
• Write to projects/001-payment-gateway-modernization/ARC-001-REQ-v1.0.md
• Confirm completion with summary

Important Notes

• Requirements drive everything: SOW, vendor evaluation, design reviews, testing
• Be specific and measurable (avoid "fast", use "< 2 seconds")
• Include WHY (rationale) not just WHAT
• Make acceptance criteria testable
• Flag compliance requirements clearly (PCI-DSS, HIPAA, SOX, GDPR, etc.)
• 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

Suggested Next Steps

After completing this command, consider running:

• $arckit-data-model -- Create data model from data requirements (when DR-xxx data requirements were generated)
• $arckit-research -- Research technology options
• $arckit-risk -- Create risk register from requirements
• $arckit-dpia -- Assess data protection impact