Optional Artifact Handler Skill

Handles optional artifact inputs in workflows, allowing workflows to proceed with or without optional artifacts.

When to Use

Use this skill when:

• Executing workflow steps with inputs marked as (optional) in YAML
• Building adaptive workflows that gracefully degrade without certain inputs
• Implementing fallback logic for missing documentation artifacts
• Documenting decision rationale about optional artifact handling
• Recovering from incomplete previous steps without blocking progress

Trigger Phrases:

• "Check for optional artifact X"
• "Handle missing optional input"
• "Provide defaults for optional artifact"
• "Process step with optional artifacts"

Invocation Examples

Natural Language (Recommended)

"Check if infrastructure-config.json is available as an optional input"
"Handle the optional UX spec artifact for code review"
"Provide defaults for missing test-plan from Step 5"

Skill Tool (Programmatic)

// In agent workflow execution
Skill: optional-artifact-handler

// With specific context
await skillManager.invoke('optional-artifact-handler', {
  artifactName: 'infrastructure-config.json',
  workflowId: 'workflow-123',
  step: 7
});

Instructions

Step 1: Detect Optional Artifacts

1. Check workflow step definition:

   • Review step inputs in workflow YAML
   • Identify which inputs are marked as optional
   • Check artifact registry for availability

2. Check artifact registry:

   • Location: .claude/context/artifacts/registry-{workflow_id}.json
   • Check if optional artifact exists
   • Verify artifact validation status if present

Example Registry Check:

{
  "artifacts": [
    {
      "name": "infrastructure-config.json",
      "path": ".claude/context/artifacts/infrastructure-config-workflow-123.json",
      "step": 4.5,
      "agent": "devops",
      "validated": true,
      "created_at": "2025-01-03T10:30:00Z"
    }
  ]
}

Step 2: Handle Missing Optional Artifacts

1. If artifact missing:

   • Log in reasoning file: "Optional artifact {name} not found, using default"
   • Use default value or behavior
   • Continue workflow execution

2. If artifact present:

   • Load artifact from registry
   • Verify validation status
   • Use artifact value

Example Handling Logic:

// Check registry
const registry = await readFile('.claude/context/artifacts/registry-workflow-123.json');
const artifact = registry.artifacts.find(a => a.name === 'infrastructure-config.json');

if (!artifact) {
  // Missing optional artifact - use defaults
  console.log('[optional-artifact-handler] infrastructure-config.json not found, using empty config');
  const config = { resources: [], environment_variables: {} };

  // Log decision
  await appendToReasoningFile({
    optional_artifact_handling: {
      artifact: 'infrastructure-config.json',
      status: 'missing',
      default_used: 'empty config object',
      impact: 'Cloud service integration stubs will use placeholder values'
    }
  });

  return config;
} else {
  // Artifact available - load it
  console.log('[optional-artifact-handler] infrastructure-config.json found, loading from registry');
  const config = await readFile(artifact.path);

  // Log decision
  await appendToReasoningFile({
    optional_artifact_handling: {
      artifact: 'infrastructure-config.json',
      status: 'available',
      source: artifact.path,
      impact: 'Cloud service integration will use actual resource names'
    }
  });

  return config;
}

Step 3: Provide Defaults

1. Default values:

   • Use sensible defaults based on workflow context
   • Document default choice in reasoning file
   • Ensure defaults don't break workflow

2. Default behaviors:

   • Skip optional step if artifact missing
   • Use fallback logic when artifact unavailable
   • Continue with reduced functionality

Example Default Strategies:

Step 4: Document Handling

1. Log in reasoning file:

   • Document which optional artifacts were used
   • Document which defaults were applied
   • Record decision rationale

2. Update plan:

   • Note optional artifact handling in plan
   • Document impact on workflow execution
   • Track optional artifact usage

Example Reasoning File Output:

{
  "step": 7,
  "agent": "developer",
  "optional_artifact_handling": {
    "timestamp": "2025-01-03T10:45:00Z",
    "artifacts_checked": [
      {
        "name": "infrastructure-config.json",
        "required": false,
        "found": false,
        "default_applied": "empty config object",
        "impact": "Cloud integration stubs will use placeholder resource names"
      },
      {
        "name": "ui-spec.json",
        "required": false,
        "found": true,
        "source": ".claude/context/artifacts/ui-spec-workflow-123.json",
        "impact": "UI components will follow specified design system"
      }
    ],
    "workflow_impact": "Proceeded with partial context - cloud integration requires manual configuration",
    "recommendations": [
      "Run DevOps step (4.5) to generate infrastructure-config.json",
      "Update cloud service stubs with actual resource names after infrastructure provisioning"
    ]
  }
}

Complete Workflow Example

Scenario: Developer Step with Optional Infrastructure Config

Workflow YAML (Step 7):

- step: 7
  agent: developer
  prompt: Implement API endpoints and cloud integration
  inputs:
    - plan.json (from step 3)
    - architecture.json (from step 4)
    - infrastructure-config.json (from step 4.5, optional)
  outputs:
    - dev-manifest.json
  validation:
    schema: .claude/schemas/dev_manifest.schema.json

Step 1: Check Registry

# Agent reads artifact registry
cat .claude/context/artifacts/registry-workflow-123.json

# Output:
# {
#   "artifacts": [
#     {
#       "name": "plan.json",
#       "path": ".claude/context/artifacts/plan-workflow-123.json",
#       "step": 3,
#       "validated": true
#     },
#     {
#       "name": "architecture.json",
#       "path": ".claude/context/artifacts/architecture-workflow-123.json",
#       "step": 4,
#       "validated": true
#     }
#     // Note: infrastructure-config.json is MISSING
#   ]
# }

Step 2: Detect Missing Optional Artifact

// Developer agent logic
const requiredArtifacts = ['plan.json', 'architecture.json'];
const optionalArtifacts = ['infrastructure-config.json'];

// Check required artifacts (must exist)
for (const artifact of requiredArtifacts) {
  const found = registry.artifacts.find(a => a.name === artifact);
  if (!found) {
    throw new Error(`Required artifact ${artifact} not found`);
  }
}

// Check optional artifacts (graceful degradation)
const infraConfig = registry.artifacts.find(a => a.name === 'infrastructure-config.json');
if (!infraConfig) {
  console.log('[optional-artifact-handler] infrastructure-config.json missing - using defaults');
}

Step 3: Apply Defaults

// Use default empty infrastructure config
const infrastructureConfig = infraConfig
  ? await readFile(infraConfig.path)
  : {
      cloud_provider: 'gcp',
      resources: [],
      environment_variables: {},
      service_accounts: []
    };

// Generate code with placeholders
const storageClient = `
// TODO: Update with actual bucket name from infrastructure-config.json
const bucketName = process.env.STORAGE_BUCKET || 'placeholder-bucket';
const storage = new Storage({ projectId: process.env.GCP_PROJECT_ID });
`;

Step 4: Document in Reasoning File

{
  "step": 7,
  "agent": "developer",
  "optional_artifact_handling": {
    "timestamp": "2025-01-03T10:45:00Z",
    "missing_optional_artifacts": ["infrastructure-config.json"],
    "defaults_applied": {
      "infrastructure-config.json": {
        "default_value": "empty config with placeholder resource names",
        "rationale": "DevOps step (4.5) was skipped - proceeding with stubs",
        "workaround": "Using environment variables and placeholder names",
        "follow_up_required": true,
        "follow_up_action": "Run DevOps step to generate actual infrastructure config"
      }
    },
    "code_generation_impact": [
      "Cloud storage client uses placeholder bucket name",
      "Database connection uses placeholder credentials",
      "Message queue client uses default topic names"
    ],
    "runtime_requirements": [
      "Set STORAGE_BUCKET environment variable before deployment",
      "Set DATABASE_URL environment variable before deployment",
      "Configure GCP_PROJECT_ID environment variable"
    ]
  }
}

Step 5: Continue Execution

// Developer continues with implementation
const manifest = {
  files_created: [
    'src/services/storage.ts',  // Uses placeholder bucket name
    'src/services/database.ts', // Uses placeholder connection string
    'src/api/upload.ts'         // API endpoint implementation
  ],
  files_modified: [],
  dependencies_added: ['@google-cloud/storage', 'pg'],
  tests_created: ['tests/api/upload.test.ts'],
  notes: [
    'infrastructure-config.json was not available',
    'Cloud service clients use placeholder resource names',
    'Run DevOps step (4.5) and update service configurations'
  ]
};

// Save manifest
await writeFile('.claude/context/artifacts/dev-manifest-workflow-123.json', manifest);

Optional Artifact Patterns

Pattern 1: Optional Documentation

Use Case: Code review can proceed without PRD or UX spec

- step: 8
  agent: code-reviewer
  inputs:
    - dev-manifest.json (from step 7)
    - prd.json (from step 2, optional)
    - ui-spec.json (from step 4.1, optional)

Handling Logic:

const prd = await loadOptionalArtifact('prd.json');
const uiSpec = await loadOptionalArtifact('ui-spec.json');

const reviewChecks = {
  code_quality: true,           // Always check
  architecture_compliance: true, // Always check
  prd_alignment: !!prd,         // Only if PRD available
  ui_compliance: !!uiSpec       // Only if UI spec available
};

if (!prd) {
  console.log('[code-reviewer] PRD not available - skipping requirements alignment check');
}

if (!uiSpec) {
  console.log('[code-reviewer] UI spec not available - skipping design system compliance');
}

Pattern 2: Optional Previous Artifacts

Use Case: Architect can design without existing legacy system analysis

- step: 4
  agent: architect
  inputs:
    - prd.json (from step 2)
    - legacy-analysis.json (from step 3.5, optional)

Handling Logic:

const legacyAnalysis = await loadOptionalArtifact('legacy-analysis.json');

const architectureConstraints = legacyAnalysis
  ? {
      legacy_integrations: legacyAnalysis.integration_points,
      migration_requirements: legacyAnalysis.migration_strategy,
      compatibility_constraints: legacyAnalysis.constraints
    }
  : {
      legacy_integrations: [],
      migration_requirements: 'greenfield',
      compatibility_constraints: []
    };

Pattern 3: Optional Validation Artifacts

Use Case: QA can test without performance benchmarks

- step: 9
  agent: qa
  inputs:
    - dev-manifest.json (from step 7)
    - performance-baseline.json (from step 8.5, optional)

Handling Logic:

const performanceBaseline = await loadOptionalArtifact('performance-baseline.json');

const testSuite = {
  unit_tests: true,              // Always run
  integration_tests: true,        // Always run
  e2e_tests: true,               // Always run
  performance_tests: !!performanceBaseline  // Only if baseline available
};

if (!performanceBaseline) {
  console.log('[qa] Performance baseline not available - skipping performance regression tests');
  console.log('[qa] Will establish new baseline instead of comparing against existing');
}

Example Output/Logging Format

Console Logging Pattern

[optional-artifact-handler] Checking for optional artifact: infrastructure-config.json
[optional-artifact-handler] Registry path: .claude/context/artifacts/registry-workflow-123.json
[optional-artifact-handler] ✗ infrastructure-config.json NOT FOUND (optional)
[optional-artifact-handler] ✓ Applying default: empty config object
[optional-artifact-handler] Impact: Cloud integration stubs will use placeholder values
[optional-artifact-handler] Recommendation: Run DevOps step (4.5) to generate infrastructure config
[optional-artifact-handler] Documenting decision in reasoning file

Reasoning File Entry

{
  "optional_artifact_handling": {
    "timestamp": "2025-01-03T10:45:00Z",
    "workflow_id": "workflow-123",
    "step": 7,
    "agent": "developer",
    "artifacts_checked": [
      {
        "name": "infrastructure-config.json",
        "required": false,
        "found": false,
        "registry_path": ".claude/context/artifacts/registry-workflow-123.json",
        "default_strategy": "empty_config",
        "default_value": {
          "cloud_provider": "gcp",
          "resources": [],
          "environment_variables": {},
          "service_accounts": []
        },
        "impact_assessment": {
          "severity": "medium",
          "areas_affected": ["cloud_integration", "deployment"],
          "workarounds_applied": ["environment_variables", "placeholder_names"],
          "follow_up_required": true,
          "follow_up_steps": ["Run step 4.5 (DevOps)", "Update service configurations"]
        }
      }
    ],
    "workflow_continuity": "proceeded_with_defaults",
    "quality_impact": "technical_debt_introduced",
    "recommendations": [
      "Run DevOps workflow step (4.5) to generate infrastructure-config.json",
      "Update cloud service clients with actual resource names after infrastructure provisioning",
      "Set required environment variables before deployment"
    ]
  }
}

Artifact Registry Update

{
  "artifacts": [
    {
      "name": "dev-manifest.json",
      "path": ".claude/context/artifacts/dev-manifest-workflow-123.json",
      "step": 7,
      "agent": "developer",
      "validated": true,
      "created_at": "2025-01-03T10:50:00Z",
      "metadata": {
        "optional_artifacts_used": [],
        "optional_artifacts_missing": ["infrastructure-config.json"],
        "defaults_applied": ["infrastructure-config.json"],
        "quality_notes": "Cloud integration uses placeholder values - requires manual configuration"
      }
    }
  ]
}

Related Documentation

• Orchestrator Agent - Optional Input Handling
• Developer Agent - Cloud Integration Patterns
• Workflow Guide - Optional Inputs Section
• CUJ-038 - Optional Artifact Handling