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

```text
$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/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)
   - **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]` → Default to "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

**Calculated fields**:

- `[YYYY-MM-DD]` for Review Date → Current date + 30 days (requirements, research, risks)
- `[YYYY-MM-DD]` for 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

```markdown
| 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:

```markdown
**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-4-5-20250929"]
**Generation Context**: [Brief note about source documents used]
```

### Example Fully Populated Document Control Section

```markdown
## Document Control

| Field | Value |
|-------|-------|
| **Document ID** | ARC-001-REQ-v1.0 |
| **Document Type** | {Document purpose} |
| **Project** | Windows 10 to Windows 11 Migration (Project 001) |
| **Classification** | OFFICIAL-SENSITIVE |
| **Status** | DRAFT |
| **Version** | 1.0 |
| **Created Date** | 2025-10-29 |
| **Last Modified** | 2025-10-29 |
| **Review Date** | 2025-11-30 |
| **Owner** | John Smith (Business Analyst) |
| **Reviewed By** | [PENDING] |
| **Approved By** | [PENDING] |
| **Distribution** | PM Team, Architecture Team, Dev Team |

## 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:

   ```markdown
   ## 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 `$arckit-research` 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