Item Types and Hierarchy

The Test & Accept platform uses a flexible item type system that separates high-level planning from specific execution while maintaining clear hierarchical relationships. This approach enables better project organization and more effective testing strategies.

The Item Type System

Core Philosophy

The item type system is built on the principle that different types of work require different behaviors:

• Strategic Planning needs broad organization and status aggregation
• Tactical Execution needs specific, testable outcomes
• Clear Separation between planning and execution prevents confusion
• Hierarchical Structure maintains logical relationships

Evolution from Task Items

Previously, the platform used a generic "task items" approach where all items were treated the same. The new system provides:

• Type-Specific Behaviors: Different rules and capabilities for different purposes
• Visual Differentiation: Clear icons and styling to distinguish item types
• Hierarchy Validation: Logical constraints that prevent confusing structures
• Future Extensibility: Foundation for additional item types (milestones, deliverables)

Item Types

Requirements (🔷)

Purpose: High-level work organization and planning

Examples of Good Requirements:

• "User Authentication System"
• "Payment Processing Module"
• "Admin Dashboard Features"
• "API Integration Layer"
• "Mobile App Features"

Task Items (📋)

Purpose: Specific, actionable work with testable outcomes

Examples of Good Task Items:

• "Implement OAuth login flow"
• "Add password strength validation"
• "Create user registration API endpoint"
• "Design payment form UI"
• "Configure Stripe webhook handling"

Hierarchical Rules

Allowed Nesting Patterns

✅ VALID HIERARCHIES:

🔷 Requirement
  ├── 🔷 Sub-requirement
  ├── 📋 Task item
  └── 📋 Task item
      └── 📋 Sub-task

🔷 Requirement  
  ├── 📋 Task item
  └── 📋 Task item

📋 Task item
  ├── 📋 Sub-task
  └── 📋 Sub-task

Prohibited Nesting Patterns

❌ INVALID HIERARCHIES:

📋 Task item
  └── 🔷 Requirement  ← Cannot nest requirement under task item

🔷 Requirement
  └── 🔷 Requirement
      └── 📋 Task item
          └── 🔷 Requirement  ← Violates logical flow

Validation Logic

The system enforces these rules automatically:

1. Requirements can contain any item type except dependencies
2. Task Items can only contain other task items (sub-tasks)
3. Circular References are prevented at all levels
4. Logical Flow is maintained from planning → execution

Real-World Project Examples

E-commerce Platform

🔷 User Management (requirement)
  ├── 📋 User registration system (task_item)
  │   ├── 📋 Email validation (task_item)
  │   ├── 📋 Password strength checking (task_item)
  │   └── 📋 Email verification flow (task_item)
  ├── 📋 User authentication (task_item)
  │   ├── 📋 Login form (task_item)
  │   ├── 📋 Session management (task_item)
  │   └── 📋 Logout functionality (task_item)
  └── 🔷 Profile Management (requirement)
      ├── 📋 Profile editing (task_item)
      ├── 📋 Avatar upload (task_item)
      └── 📋 Account deletion (task_item)

🔷 Payment Processing (requirement)
  ├── 📋 Stripe integration (task_item)
  │   ├── 📋 Payment form UI (task_item)
  │   ├── 📋 Webhook handling (task_item)
  │   └── 📋 Receipt generation (task_item)
  ├── 📋 Subscription management (task_item)
  └── 📋 Refund processing (task_item)

Software API Project

🔷 Authentication & Authorization (requirement)
  ├── 📋 JWT token system (task_item)
  ├── 📋 Role-based permissions (task_item)
  └── 📋 API key management (task_item)

🔷 Core API Endpoints (requirement)
  ├── 🔷 User Operations (requirement)
  │   ├── 📋 GET /users (task_item)
  │   ├── 📋 POST /users (task_item)
  │   └── 📋 PUT /users/{id} (task_item)
  └── 🔷 Data Operations (requirement)
      ├── 📋 GET /data (task_item)
      ├── 📋 POST /data (task_item)
      └── 📋 DELETE /data/{id} (task_item)

🔷 Documentation & Testing (requirement)
  ├── 📋 OpenAPI specification (task_item)
  ├── 📋 Integration tests (task_item)
  └── 📋 Performance tests (task_item)

Testing and Status Behavior

Requirements Testing

• No Direct Tests: Requirements cannot have acceptance criteria or tests
• Status Aggregation: Status is calculated from child task items
• Progress Tracking: Completion percentage based on child item completion
• Rollup Logic: All child task items must pass for requirement to be "complete"

Task Item Testing

• Direct Testing: Can have acceptance criteria and associated tests
• Pass/Fail Status: Binary outcomes based on test results
• Detailed Criteria: Multiple criteria per task item for comprehensive testing
• Verification: Each criterion must have clear pass/fail conditions

Migration from Legacy Task Items

Understanding the Transition

Before (Legacy):

📄 All items were "task items"
📄 No distinction between planning and execution
📄 Same behavior for all items regardless of purpose
📄 Testing available on all items

After (Current):

🔷 Requirements for planning and organization
📋 Task items for specific, testable work
Different behaviors for different purposes
Testing only where it makes logical sense

Backward Compatibility

• Existing Items: Legacy task items are preserved as task_item type
• API Compatibility: Old endpoints continue to work
• Gradual Migration: Teams can adopt new types at their own pace
• No Data Loss: All existing content and relationships preserved

Best Practices

When to Use Requirements

• Organizing Work: Group related task items under common themes
• Project Phases: Major milestones or deliverable categories
• Feature Sets: Collections of related functionality
• Stakeholder Communication: High-level items for client/management visibility

When to Use Task Items

• Specific Work: Individual features, fixes, or implementations
• Testable Outcomes: Work that can be verified with acceptance criteria
• Developer Tasks: Items that developers will directly implement
• Detailed Planning: When you need to define specific acceptance criteria

Hierarchy Design

• Start High-Level: Begin with requirements to establish structure
• Progressive Detail: Break requirements into specific task items
• Logical Grouping: Group related work under appropriate requirements
• Balanced Depth: Avoid excessive nesting (typically 2-3 levels)

Naming Conventions

Requirements: Use noun phrases describing work areas

• ✅ "User Authentication System"
• ✅ "Payment Processing Module"
• ❌ "Implement user login" (too specific)

Task Items: Use action phrases describing specific work

• ✅ "Implement OAuth login flow"
• ✅ "Add password validation"
• ❌ "Authentication" (too broad)

Future Item Types

The system is designed for extensibility. Planned future types include:

Milestones (🎯)

• Time-based project checkpoints
• Target dates and deliverable gates
• Critical path analysis
• Stakeholder notifications

Deliverables (📦)

• Client-facing outputs
• Approval workflows
• Document management
• Version control

Dependencies (⚠️)

• External blocking items
• Vendor coordination
• Risk management
• SLA tracking

API Integration

Type-Aware Queries

// Get only requirements
const requirements = await apiClient.get('/api/sow/123/items?type=requirement');

// Get only task items
const taskItems = await apiClient.get('/api/sow/123/items?type=task_item');

// Get items by parent
const childItems = await apiClient.get('/api/sow/123/items?parentId=item_456');

Creating Typed Items

// Create a requirement
const requirement = await apiClient.post('/api/sow/123/items', {
  title: "User Management System",
  description: "Complete user auth and profile management",
  type: "requirement"
});

// Create a task item under the requirement
const taskItem = await apiClient.post('/api/sow/123/items', {
  title: "Implement user registration",
  description: "Create registration form and API endpoint", 
  type: "task_item",
  parentId: requirement.id
});

For complete API details, refer to the API Reference.