Normalize

Appearance

Workflow Design ​

Design documents for structured patterns accomplishing common software engineering tasks. These patterns inform spore workflow implementations.

What is a Workflow? ​

A workflow is a repeatable pattern that combines:

  • Trigger: What initiates it (user request, file change, schedule)
  • Goal: What success looks like
  • Tools: Which normalize primitives are needed
  • Decomposition: How to break it into steps
  • Validation: How to verify it worked

Workflow Categories ​

Investigation (understanding) ​

Modification (changing) ​

Review (auditing) ​

Maintenance (keeping healthy) ​

Workflow Anatomy ​

Each workflow document should cover:

## Trigger
What initiates this workflow? User request, file change, CI, schedule?

## Goal
What does success look like? Concrete deliverable or state change?

## Prerequisites
What must be true before starting? Index built, tests passing, etc.

## Decomposition Strategy
How to break this into steps? Sequential, parallel, recursive?

## Tools Used
Which normalize primitives? view, edit, text-search, analyze, etc.

## Validation
How to verify success? Tests pass, lint clean, human approval?

## Failure Modes
What can go wrong? How to detect and recover?

## Example Session
Concrete example of the workflow in action.

## Variations
Different flavors of this workflow for different contexts.

Design Principles ​

1. Search Before Act ​

RLM research shows: filtering/searching before LLM processing is 3x cheaper and more accurate. Every modification workflow should start with investigation.

2. Validate Early and Often ​

Don't batch validation at the end. Check after each step where possible. Fail fast.

3. Decompose Recursively ​

Large tasks should spawn sub-tasks. The depth of recursion should match the complexity of the task.

4. Preserve Reversibility ​

Prefer workflows that can be undone. Shadow editing, git commits as checkpoints, etc.

5. Explicit Over Implicit ​

Log decisions, show what was considered, explain why alternatives were rejected.

Workflow Composition ​

Workflows can compose:

  • Sequential: Bug Investigation → Bug Fix → Code Review
  • Nested: Feature Implementation contains multiple Refactoring sub-workflows
  • Conditional: If tests fail after edit, spawn Bug Investigation

Edge Case Workflows (to explore) ​

Unusual or challenging scenarios that don't fit standard patterns:

Investigation Edge Cases ​

  • Reverse Engineering Code - understanding undocumented/legacy code with no context
  • Reverse engineering binary formats - understanding file formats, protocols without docs
  • Debugging production issues - working from logs/traces without local reproduction
  • Performance regression hunting - finding what made things slow
  • Flaky test debugging - non-deterministic failures, timing issues, environment dependencies

Modification Edge Cases ​

  • Merge conflict resolution - understanding both sides, choosing correct resolution
  • Cross-language migration - porting code between languages (Python→Rust, JS→TS)
  • Breaking API changes - handling upstream dependency changes that break your code
  • Dead code elimination - safely removing unused code paths

Synthesis Edge Cases (low training data) ​

  • High-quality code synthesis - generating correct code with minimal examples
    • Extract patterns from sparse existing data
    • Use test suites from reference implementations (other languages) as specification
    • Cartesian product: compare each doc page against all synthesized code
    • Introspect generated code for internal consistency
    • Iterative refinement against known-good tests
  • Binding Generation - generating FFI/bindings for libraries
  • Grammar/Parser Generation - creating parsers from examples + informal specs

Meta Workflows ​

Security/Forensic Edge Cases ​

Implementation Status ​

WorkflowStatusNotes
Question AnsweringDocumentedInvestigator role in agent
Bug FixDocumented-
Code ReviewDocumented-
Code SynthesisDocumentedD×C verification, low-data domains
Binary REDocumentedHypothesis-driven differential analysis
Flaky Test DebuggingDocumentedRace detectors, CI diagnosis, Antithesis
Perf RegressionDocumentedProfiling, distributed tracing, continuous profiling
Merge ConflictsDocumentedSemantic merge, resolution reasoning logs
Dead Code EliminationDocumentedRuntime tracing, tree shaking, tombstoning
Codebase OnboardingDocumentedSurvey → Trace → Map → Verify
Production DebuggingDocumentedScope → Correlate → Hypothesize → Verify
Cross-Language MigrationDocumentedConcept mapping, verification, incremental
Breaking API ChangesDocumentedAssess, compatibility shims, semantic verification
Reverse Eng. CodeDocumentedExecute → Trace → Understand → Document
Binding GenerationDocumentedAnalyze → Generate → Wrap → Test
Grammar/Parser GenDocumentedCollect → Infer → Generate → Validate
Documentation SynthDocumentedExtract → Organize → Generate → Validate
CryptanalysisDocumentedSurvey → Analyze → Verify → Report
SteganographyDocumentedTriage → Analyze → Extract → Verify
Malware AnalysisDocumentedTriage → Static → Dynamic → Document
Debugging PracticesDocumentedIssues log, debug tooling, golden tests
Security AuditDocumentedScope → Survey → Deep Dive → Report
Feature ImplementationDocumentedUnderstand → Design → Implement → Verify
Cross-Workflow AnalysisDocumentedShared patterns and principles

Living Documents ​

These workflows are perpetually incomplete. They capture current understanding and known techniques, but:

  • New tools emerge (pattern languages, analysis frameworks)
  • Edge cases surface during real usage
  • Better decomposition strategies are discovered
  • LLM capabilities evolve, changing what's automatable

Treat each workflow as a starting point, not a complete prescription. Update as you learn.

See Also ​