generate

Intent

Produce a new artifact that satisfies specified constraints and serves a defined purpose. Generation is creative synthesis bounded by requirements, not mere retrieval or transformation.

Success criteria:

• Artifact satisfies all stated constraints
• Rationale explains design decisions
• Quality signals demonstrate fitness for purpose
• Safety considerations documented

Compatible schemas:

• schemas/output_schema.yaml

Inputs

Inputs not listed here are outside the capability's contract: a workflow step that binds them gets W604 (STANDARD v1.1 §5.5).

Procedure

1. Clarify artifact requirements: Ensure constraints are understood
   • Must-have: absolute requirements (format, structure, compatibility)
   • Should-have: preferences (style, conventions, optimization)
   • Must-not-have: exclusions (patterns to avoid, security constraints)
2. Gather context: Collect relevant reference material
   • Read existing code/docs for style consistency
   • Identify patterns to follow or avoid
   • Understand integration points and dependencies
3. Design approach: Plan the generation strategy
   • Outline structure before detailed generation
   • Consider multiple approaches if request is complex
   • Document key design decisions
4. Generate artifact: Produce the content systematically
   • Follow identified patterns and conventions
   • Satisfy constraints in priority order
   • Document any constraints that conflict
5. Validate constraints: Verify each constraint is satisfied
   • Mark each constraint as satisfied/unsatisfied
   • Note any compromises or partial satisfaction
6. Assess quality: Evaluate fitness for purpose
   • Correctness: Does it work as intended?
   • Completeness: Is anything missing?
   • Maintainability: Is it understandable and modifiable?
   • Safety: Are there security or reliability concerns?
7. Document rationale: Explain why this design
   • Key decisions and their reasoning
   • Alternatives considered and why rejected
   • Known limitations or future considerations
8. Ground claims: Reference sources that informed generation

Output Contract

Return a structured object:

content: string | object  # The generated artifact
metadata:  # Generation metadata
  type: string  # text, code, plan, config, schema, etc.
  format: string  # markdown, json, yaml, typescript, etc.
constraints_used:
  - constraint: string  # Constraint description
    satisfied: boolean  # Was it met?
    notes: string  # How it was satisfied or why not
rationale: string  # Why this design/approach
alternatives_considered: array[string]  # Other approaches evaluated
quality_signals:
  - metric: string  # Quality dimension
    value: number | string  # Assessment
confidence: number  # 0.0-1.0 in artifact quality
evidence_anchors: array[string]  # References to source material
assumptions: array[string]  # Conditions affecting the artifact
safety_notes: array[string]  # Security/reliability considerations
next_actions: array[string]  # Suggested follow-ups

Field Definitions

Examples

Example 1: Generate API Endpoint

Input:

specification:
  artifact_type: "code"
  endpoint: "POST /api/users"
  schema: "{ name: string, email: string, role: 'admin' | 'user' }"
constraints:
  must_have:
    - "TypeScript with strict mode"
    - "Express.js middleware pattern"
    - "Input validation with Zod"
    - "Return 200 on success, 400 on validation error, 500 on server error"
format: "typescript"

Output:

content: |
  import { Request, Response, NextFunction } from 'express';
  import { z } from 'zod';

  const CreateUserSchema = z.object({
    name: z.string().min(1).max(100),
    email: z.string().email(),
    role: z.enum(['admin', 'user'])
  });

  type CreateUserInput = z.infer<typeof CreateUserSchema>;

  export async function createUser(
    req: Request,
    res: Response,
    next: NextFunction
  ): Promise<void> {
    try {
      const parsed = CreateUserSchema.safeParse(req.body);

      if (!parsed.success) {
        res.status(400).json({
          error: 'Validation failed',
          details: parsed.error.issues
        });
        return;
      }

      const userData: CreateUserInput = parsed.data;

      // TODO: Implement actual user creation logic
      const user = await userService.create(userData);

      res.status(200).json({ user });
    } catch (error) {
      next(error);
    }
  }
metadata:
  type: "code"
  format: "typescript"
constraints_used:
  - constraint: "TypeScript with strict mode"
    satisfied: true
    notes: "All types explicit, strict null checks compatible"
  - constraint: "Express.js middleware pattern"
    satisfied: true
    notes: "Standard (req, res, next) signature with async handler"
  - constraint: "Input validation with Zod"
    satisfied: true
    notes: "Zod schema with safeParse for type-safe validation"
  - constraint: "HTTP status codes"
    satisfied: true
    notes: "200 success, 400 validation error, 500 via error middleware"
rationale: "Used safeParse over parse for explicit error handling without exceptions. Separated schema definition for reuse in tests. Left business logic as TODO for service layer."
alternatives_considered:
  - "class-validator with decorators - rejected for runtime overhead"
  - "Manual validation - rejected for type safety"
quality_signals:
  - metric: "type_safety"
    value: "high"
  - metric: "error_handling"
    value: "comprehensive"
  - metric: "testability"
    value: "high"
confidence: 0.9
evidence_anchors:
  - "zod:docs:safeParse"
  - "express:docs:error-handling"
assumptions:
  - "userService exists and is imported"
  - "Error middleware handles uncaught exceptions"
safety_notes:
  - "Email validation does not prevent all injection attacks"
  - "Consider rate limiting for user creation endpoint"
next_actions:
  - "Implement userService.create method"
  - "Add authentication middleware"
  - "Write unit tests for validation logic"

Evidence pattern: Read existing codebase for patterns, reference library documentation for best practices.

Example 2: Generate Configuration Schema

Input:

specification:
  artifact_type: "schema"
  description: "Database connection configuration"
constraints:
  must_have:
    - "JSON Schema draft-07"
    - "Required fields: host, port, database"
    - "Optional: ssl, poolSize, timeout"
  should_have:
    - "Sensible defaults where appropriate"
format: "json"

Output:

content:
  $schema: "http://json-schema.org/draft-07/schema#"
  title: "DatabaseConfig"
  type: "object"
  required: ["host", "port", "database"]
  properties:
    host:
      type: "string"
      description: "Database server hostname"
      examples: ["localhost", "db.example.com"]
    port:
      type: "integer"
      minimum: 1
      maximum: 65535
      description: "Database server port"
      default: 5432
    database:
      type: "string"
      description: "Database name"
      minLength: 1
    ssl:
      type: "boolean"
      description: "Enable SSL/TLS connection"
      default: true
    poolSize:
      type: "integer"
      minimum: 1
      maximum: 100
      description: "Connection pool size"
      default: 10
    timeout:
      type: "integer"
      minimum: 0
      description: "Connection timeout in milliseconds"
      default: 30000
  additionalProperties: false
metadata:
  type: "schema"
  format: "json"
constraints_used:
  - constraint: "JSON Schema draft-07"
    satisfied: true
    notes: "$schema declaration included"
  - constraint: "Required fields: host, port, database"
    satisfied: true
    notes: "Listed in required array"
  - constraint: "Optional: ssl, poolSize, timeout"
    satisfied: true
    notes: "Not in required, have defaults"
  - constraint: "Sensible defaults"
    satisfied: true
    notes: "port=5432 (PostgreSQL), ssl=true, poolSize=10, timeout=30s"
rationale: "Used PostgreSQL port as default assuming most common use case. SSL enabled by default for security. Pool size 10 balances resource usage with concurrency."
alternatives_considered:
  - "MySQL port 3306 - rejected, PostgreSQL more common in modern stacks"
quality_signals:
  - metric: "completeness"
    value: "high"
  - metric: "documentation"
    value: "descriptions and examples included"
confidence: 0.95
evidence_anchors:
  - "json-schema:draft-07:spec"
assumptions:
  - "PostgreSQL is the target database"
  - "Production deployment expects SSL"
safety_notes:
  - "Consider encrypting credentials in actual config files"
  - "poolSize limits should match database max_connections"
next_actions:
  - "Add validation for connection string format"
  - "Consider environment variable substitution"

Verification

• All required constraints marked as satisfied
• Artifact format matches requested format
• Quality signals include at least correctness and completeness
• Rationale explains key design decisions
• Safety notes address security considerations

Verification tools: Read (for pattern consistency), schema validators, linters

Safety Constraints

• mutation: false
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:

• Generated code must not contain hardcoded secrets or credentials
• Flag any security-sensitive patterns in generated content
• Do not generate content that violates constraints - report conflicts instead
• Include safety_notes for any security-relevant artifact

Composition Patterns

Commonly follows:

• compare - Generate solution based on comparison winner
• plan - Generate artifacts specified in plan
• identify - Generate based on identified requirements
• discover - Generate to address discovered gaps

Commonly precedes:

• verify - Generated artifacts should be verified
• act - Generated content may be written to files
• critique - Generated plans should be critiqued

Anti-patterns:

• Never generate without constraints (unbounded generation)
• Avoid generate for retrieval (use search or retrieve)
• Do not use generate for analysis (use estimate, compare, etc.)

Workflow references:

• See reference/composition_patterns.md#capability-gap-analysis for generate-plan usage
• See reference/composition_patterns.md#debug-code-change for code generation in fixes