platform-constraints

# platform-constraints

**Produces**: Comprehensive analysis of platform limitations, quotas, and implementation patterns  
**Solves**: "What are the real constraints and gotchas of this technology platform?"

## Input Contract

### Required Input
- `<prompt-context>`: Platform name and investigation focus
- Example: "Google Apps Script execution limits and state management patterns"

### Optional Input
- `--rehydrate-from <path>`: Path to previous platform analysis
- `--focus-areas <list>`: Specific areas to investigate (execution, storage, auth, etc.)
- `--scale-target <number>`: Target user/request scale for limit testing

## Output Contract

```yaml
deliverable_type: platform_constraints
generated_at: [timestamp]
platform_analyzed: [technology name and version]
investigation_duration: [time spent on analysis]
confidence_level: [high|medium|low based on testing depth]

execution_model:
  runtime_environment: [V8, Node.js, JVM, etc.]
  concurrency_model: [single-threaded, event-loop, multi-threaded]
  test_code_executed: |
    [Actual code used to probe platform limits]
  empirical_findings:
    cold_start_time: [measured milliseconds]
    max_execution_time: [measured seconds/minutes]
    memory_limit: [measured MB]
    cpu_throttling: [when and how much]
    concurrent_requests: [maximum parallel operations]

storage_constraints:
  state_layers:
    request_state:
      persistence: [none|memory|disk]
      lifetime: [request duration|session|permanent]
    session_state:
      storage_location: [client|server|distributed]
      size_limit: [KB/MB limit]
      expiration: [timeout behavior]
    application_state:
      shared_access: [read-only|read-write|locked]
      synchronization: [how conflicts resolved]
    persistent_state:
      storage_type: [database|file|object store]
      size_limits: [per-record and total]
      query_limitations: [SQL subset, NoSQL patterns]

networking_model:
  protocols_supported: [HTTP, WebSocket, TCP, UDP]
  connection_limits: [concurrent connections]
  request_size_limits: [payload limits]
  response_streaming: [supported patterns]
  external_api_access: [restrictions and quotas]

authentication_flow:
  supported_methods: [OAuth, JWT, API keys, etc.]
  token_storage: [where tokens persist]
  session_management: [how sessions maintained]
  permission_evaluation: [when/where checked]
  security_boundaries: [what's isolated]

discovered_quotas:
  hard_limits:
    - quota_type: [API calls, storage, execution time]
      limit_value: [numerical limit]
      scope: [per user, per app, per second]
      test_evidence: [how discovered]
      workaround: [if any exists]
  
  soft_limits:
    - limit_type: [performance degradation points]
      threshold: [when performance degrades]
      impact: [how performance affected]
      mitigation: [how to optimize]

production_patterns:
  required_patterns:
    - pattern_name: [initialization, error handling, etc.]
      code_example: |
        [Copy-paste ready code that MUST be used]
      reason_required: [why this pattern is mandatory]
      failure_consequence: [what happens without it]
  
  anti_patterns:
    - pattern_name: [common mistake pattern]
      code_example: |
        [Code that looks right but fails]
      failure_mode: [how/when it fails]
      github_evidence: [link to issue demonstrating failure]

implementation_guide:
  boilerplate_code: |
    [Complete working starter template]
  setup_checklist:
    - [Step-by-step setup instruction]
    - [Configuration requirement]
    - [Testing verification step]
  
  testing_approach: |
    [How to test applications on this platform]
    [Platform-specific testing considerations]
  
  monitoring_strategy: |
    [What metrics to track]
    [How to debug issues]
    [Performance monitoring approach]

github_evidence:
  repositories_analyzed: [3+ production repos using platform]
  pattern_frequency: [how often patterns appear across repos]
  issue_analysis:
    common_failures: [what frequently breaks]
    workarounds_discovered: [community solutions]
    evolution_patterns: [how usage patterns changed over time]

limitations_for_use_cases:
  excellent_for:
    - [Use case where platform excels]
    - [Specific scenarios that work well]
  acceptable_for:
    - [Use cases that work but have trade-offs]
    - [Scenarios requiring workarounds]
  poor_choice_for:
    - [Use cases where platform fails]
    - [Scenarios to avoid]

scaling_analysis:
  bottleneck_identification:
    primary_bottleneck: [what limits scale first]
    secondary_bottleneck: [next limitation encountered]
  
  scaling_patterns:
    horizontal_scaling: [how to add more instances]
    vertical_scaling: [how to increase per-instance capacity]
    caching_strategies: [what and how to cache]
  
  cost_implications:
    free_tier_limits: [what's included free]
    scaling_costs: [how costs increase with usage]
    cost_optimization: [how to minimize expenses]

next_actions:
  - Reference these constraints in architecture design
  - Use boilerplate for rapid prototyping
  - Apply patterns in implementation phase
  - Monitor identified metrics in production
```

## Execution Protocol

### Step 1: Platform Profiling
Analyze the specified platform:
- Identify runtime environment and architecture
- Determine execution model (synchronous, asynchronous, event-driven)
- Map available APIs and services
- Note version differences if applicable

If `--rehydrate-from` provided:
- Load previous platform analysis
- Check for version changes that invalidate findings
- Identify gaps in previous investigation

### Step 2: Empirical Testing
Create and execute test code to discover actual limits:

```javascript
// Platform limit discovery template
function investigatePlatformLimits() {
  const tests = {
    executionTime: () => measureMaxExecutionDuration(),
    memoryUsage: () => allocateUntilLimit(),
    concurrency: () => testParallelOperations(),
    storageQuotas: () => writeUntilQuotaExceeded(),
    networkLimits: () => testRequestSizeLimits()
  };
  
  return Object.entries(tests).map(([name, test]) => ({
    test: name,
    result: test(),
    timestamp: Date.now()
  }));
}
```

### Step 3: Production Pattern Mining
Analyze 3+ GitHub repositories (500+ stars) using the platform:
- Extract common initialization patterns
- Identify configuration approaches
- Document error handling strategies
- Note performance optimizations
- Collect workarounds from Issues and Discussions

Search patterns:
- "doesn't work in production"
- "fails when deployed"
- "workaround for [platform]"
- "[platform] best practices"

### Step 4: State Management Analysis
Map how the platform handles different types of state:
- Request-scoped (dies after response)
- Session-scoped (persists across requests)
- Application-scoped (shared between users)
- Persistent (survives restarts)

Test state boundaries and synchronization mechanisms.

### Step 5: Integration Boundary Discovery
Document how platform connects to external systems:
- Database connection patterns and limitations
- API calling patterns and rate limits
- Authentication integration approaches
- File system access (if any)

### Step 6: Constraint Synthesis
Consolidate findings into actionable constraints:
- Hard limits that cannot be exceeded
- Soft limits where performance degrades
- Required patterns for successful operation
- Anti-patterns that cause failures

## Quality Gates

Before returning results, validate:
- ✅ Empirical testing performed with actual code
- ✅ At least 3 production repositories analyzed
- ✅ Both required patterns and anti-patterns documented
- ✅ Boilerplate code provided and tested
- ✅ Clear use case recommendations (good/acceptable/poor)
- ✅ Cost and scaling implications analyzed

## Example Usage

### Basic Platform Investigation
```
Ask prompter to run platform-constraints with context: "Vercel Edge Functions database connection handling and limits"
```

### Focused Investigation
```
Ask prompter to run platform-constraints with context: "Google Apps Script" and focus areas: "execution,storage,auth" and scale target: 1000 users
```

### With Previous Analysis
```
Ask prompter to run platform-constraints with context: "AWS Lambda cold starts" and rehydration from ./previous-analysis/lambda-2023.yaml
```

## Integration with Other Prompts

This prompt's output becomes input for:
- `stack-recommendation`: Constraint information influences technology choices
- `architecture-design`: Platform limits shape system design decisions
- `migration-strategy`: Understanding current platform constraints motivates migration
- `implementation-plan`: Platform patterns become implementation requirements

## Caching and Reuse

Results cached based on:
- Platform name and major version
- Investigation focus areas
- Scale targets (similar if within 2x)

Cache expiration:
- 60 days for stable platforms (AWS, Google Cloud)
- 30 days for evolving platforms (Vercel, Cloudflare)
- 7 days if platform shows rapid feature changes