How do I set up a code synthesis platform for building tickets into code changes across multiple files?

To set up a code synthesis platform that turns tickets into multi-file code changes, think of it as a pipeline with 5 parts:

1. Intake: ticket → structured task
2. Context retrieval: find relevant code/docs/tests
3. Planning: generate a change plan
4. Synthesis: edit files, create patches
5. Verification: run tests/lint/build and iterate

Here’s a practical blueprint.

---

1) Define the ticket-to-code workflow

A good system usually looks like this:

Ticket

• title, description, acceptance criteria, priority
• repo target, branch target
• constraints: style, compatibility, performance
• optional references: design docs, issue links

Normalized task Convert the ticket into a structured internal object:

• goal
• files/components likely affected
• required behavior changes
• non-goals
• test expectations

Change plan

• list of files to touch
• edit type per file (modify/add/delete)
• dependency order
• test plan

Patch output

• unified diff or structured edits
• commit message
• summary of what changed

---

2) Build the platform architecture

A solid architecture is usually:

A. Ticket service

Receives tickets from:

• Jira
• Linear
• GitHub Issues
• Zendesk / internal systems

Responsibilities:

• ingest ticket
• map to repo/project
• deduplicate
• track status

B. Code indexing and retrieval layer

Build a searchable index of the repo:

• AST-based symbol index
• text embedding search
• dependency graph
• file metadata
• test mapping

Useful data sources:

• source files
• README/docs
• package manifests
• build files
• test files
• recent commits / blame / PR history

C. Context assembler

Given a ticket, gather the minimum useful context:

• relevant files
• nearby symbols
• related tests
• error logs
• existing patterns in the codebase

This is critical: the model should not see the whole repo unless necessary.

D. Planner / orchestrator

This agent:

• reads the ticket and context
• decomposes the task
• chooses edit strategy
• requests more context if needed
• emits a structured plan

E. Code editor / synthesizer

This component performs the actual code changes:

• writes diffs
• edits multiple files consistently
• maintains formatting
• updates imports, types, tests

F. Validator

Runs checks:

• unit tests
• integration tests
• lint
• typecheck
• build
• static analysis

Then feeds failures back into the synthesize loop.

G. Review and approval

Before merge:

• human review
• CI pass
• security checks
• change summary

---

3) Use structured outputs, not free-form code only

For multi-file changes, force the model to produce structured artifacts.

A good internal schema:

{
  "ticket_id": "ABC-123",
  "goal": "Add retry logic to payment API client",
  "files_to_change": [
    {
      "path": "src/client/payments.ts",
      "action": "modify",
      "reason": "Add retry wrapper"
    },
    {
      "path": "src/client/retry.ts",
      "action": "add",
      "reason": "New reusable retry utility"
    },
    {
      "path": "tests/payments.test.ts",
      "action": "modify",
      "reason": "Cover retry behavior"
    }
  ],
  "risks": [
    "Potential duplicate retry with upstream gateway",
    "Timeout behavior may affect existing callers"
  ],
  "verification": [
    "pnpm test",
    "pnpm lint",
    "pnpm typecheck"
  ]
}

This makes orchestration much easier than asking the model for raw code immediately.

---

4) Implement context retrieval well

Multi-file synthesis depends on selecting the right context.

Best practices:

• Use symbol-aware search:
  • class/function definitions
  • references
  • call graph
• Use semantic search for ticket keywords
• Use file relationship graphs:
  • imports
  • package dependencies
  • test-to-source mapping
• Include examples of similar changes:
  • recent PRs
  • analogous implementations

Context bundle contents:

• relevant files in full, not snippets when possible
• function/class definitions around targeted code
• test cases related to the behavior
• config/build files if behavior spans tooling
• constraints from architecture docs

Keep context small but sufficient

A common failure mode is dumping too much repo text into the prompt. Prefer:

• top 5–15 relevant files
• only relevant sections if a file is large
• dynamic retrieval as the model asks for more

---

5) Make the synthesis step edit-oriented

Instead of asking “write code for this ticket,” ask the model to produce edits with constraints:

• preserve existing style
• avoid unrelated refactors
• update all references
• add tests for the exact behavior
• if unsure, leave a TODO or ask for clarification

Recommended output modes:

1. Plan only
2. Diff proposal
3. Patch application
4. Fix-up pass after tests fail

This is much more reliable than a single-shot completion.

---

6) Add an iterative repair loop

For real codebases, the first patch often fails. Your platform should automatically:

1. apply patch
2. run tests/typecheck/lint
3. parse failures
4. feed errors and relevant files back to the model
5. generate a fix patch
6. repeat until pass or max iterations

Important:

• cap iterations
• track which failures are already addressed
• prevent infinite loops
• retain a patch history

---

7) Handle multi-file coordination explicitly

Multi-file changes need consistency across:

• source code
• tests
• docs
• config
• migrations
• schemas
• API clients

Use a dependency-aware order:

1. update types/interfaces
2. implement core logic
3. update callers
4. update tests
5. update docs/config

If the ticket requires a schema or contract change, ensure all consumers are enumerated.

---

8) Add guardrails

This kind of platform can easily produce unsafe or low-quality changes, so add controls:

Safety checks

• file allow/deny lists
• secrets detection
• no production deploy changes without approval
• block destructive operations unless explicitly authorized

Quality checks

• formatting
• static typing
• test coverage requirements
• diff size limits
• complexity thresholds

Human approval gates

• high-risk files
• auth/security/payment logic
• migrations
• infra/terraform/k8s
• public APIs

---

9) Recommended implementation stack

A practical stack might be:

Backend

• Python or TypeScript
• task queue: Celery / BullMQ / Temporal
• API: FastAPI / Express
• DB: Postgres
• object store for snapshots and logs

Code analysis

• tree-sitter for parsing
• ripgrep for text search
• language-specific indexing where needed
• embeddings in a vector DB if useful

Orchestration

• workflow engine like Temporal or a job queue
• sandboxed runners for tests/builds
• containerized repo snapshots

LLM integration

• use function/tool calling for:
  • search files
  • read files
  • propose patch
  • apply patch
  • run tests
  • inspect failures

---

10) A good runtime flow

Here’s an example end-to-end flow:

1. Ticket arrives
2. System maps ticket to repo and creates task
3. Retriever finds likely files/tests/docs
4. Planner drafts implementation plan
5. Synthesizer proposes patch
6. Patch is applied in a sandbox branch
7. Tests/lint/typecheck run
8. Failures are summarized
9. Model fixes issues
10. Human reviews final PR
11. Merge after approval

---

11) Practical prompt pattern

Use a constrained prompt like:

You are editing a real repository.
Goal: implement the ticket using minimal changes.
Constraints: preserve public APIs unless ticket requires change; update tests; do not refactor unrelated code.
Available context: [files and snippets].
Output: a structured plan first, then a patch. If more context is needed, ask for specific files or symbols.

Then require a format such as:

• PLAN
• FILES TO MODIFY
• PATCH
• TEST PLAN
• RISKS

---

12) Start with a narrow MVP

Don’t start with “any ticket into any repo.”

MVP scope:

• one repository
• one ticket source
• one language
• one test runner
• patch generation + validation
• human review

Then expand:

• multiple repos
• cross-language support
• automated dependency graphs
• better ranking/retrieval
• PR generation

---

13) Metrics to track

Measure whether the platform works:

• patch acceptance rate
• test pass rate on first attempt
• average number of repair loops
• human edit distance after synthesis
• time from ticket to PR
• regression rate
• file retrieval precision
• unresolved clarifications per ticket

---

14) Common failure modes

Watch out for:

• missing a hidden dependency in another file
• over-editing unrelated code
• stale context due to branch mismatch
• test flakiness being mistaken for code failure
• non-deterministic formatting changes
• ignoring architecture constraints
• patching code that compiles but doesn’t satisfy the ticket

---

If you want, I can also give you:

1. a reference architecture diagram,
2. a database schema + task model, or
3. a minimal implementation plan in Python/TypeScript.