Skip to Content

Technical spec (TSD) review and approval

Review the technical solution design CodeLynq proposes, confirm the decisions it asks you about, put your answers into the spec, and approve it to start building.

Before CodeLynq writes code, it writes down how it will do the work: the technical solution design, or TSD. You read it, correct it and approve it. Nothing is built until a TSD is approved - this is the moment to catch a misunderstanding, when it costs nothing.

What a TSD contains

Open the task and go to the Spec tab. Under Technical Solution Design you find:

  • Functional Interpretation - how the request is understood.
  • Acceptance Criteria - one per line, what must be true for the change to count as done.
  • Technical Approach - the solution and how it will be implemented.
  • Affected Components - modules, services and files that will change.
  • Data Model Impact - database changes and migrations.
  • API Impact - new or changed endpoints.
  • Risks & Mitigations - what could go wrong, and how that is handled.
  • Test Strategy - which tests prove it works.
  • Assumptions - what was assumed where the task did not say.

Discuss the task first

While the TSD is still empty, the Spec tab shows Discuss the task first. Click Discuss first to talk the task through with the AI before anything is written: what should be built, and where. Click Let the AI ask its questions to have it start with its understanding of the task, or type what you have in mind.

On a project with several repositories the conversation is open by default. The AI knows the project's repositories and asks which ones the task touches and what changes in each.

When nothing important is open, the AI says so and Draft spec from this conversation is highlighted. Click it. The TSD is drafted from what you agreed. If the task had no repositories selected, the ones the TSD names are selected for it, so the run works in the right repositories. A selection you made yourself is never changed.

Once the TSD is there, the same conversation becomes its review: see below.

Write or propose the TSD

  • Click Propose TSD to have CodeLynq fill in every field, based on the task, the project's context and the code. The button is there while all fields are still empty.
  • Or write the fields yourself.

Review each field and change what is not right, then click Save Draft. Pay most attention to Functional Interpretation and Assumptions: if those are wrong, the rest will be too.

Review it with your technical lead

A proposed TSD does not come alone. Like a technical lead handing over a design, the AI says in a few lines how it would build it and asks you to confirm the decisions it had to make: what is in scope, how edge cases behave, what happens to existing data. Above the fields, Review with your technical lead shows how many are waiting, and Approve says so too while any are open.

  1. Click Answer the questions. Each question has suggested answers, the AI's recommendation first and marked recommended. With one question, a click on an answer sends it; with several, pick one for each and click Send answers. Other… lets you type your own.
  2. The AI says what your answers change and asks what is still open. You can also ask anything yourself: why it chose an approach, what could go wrong, whether it is ready to build.
  3. When nothing important is open, the AI says so and the bar with Update spec with these decisions turns green. Click the button: the fields are rewritten with what you agreed, edits you had not saved yet are kept, and the conversation shows what changed. A submitted TSD goes back to draft, because it no longer says what was submitted.

You can type the next message while the AI is still answering. The same conversation is on the task's Review tab, where you can also start a review yourself with Start the review.

Submit and approve

A TSD has three statuses: Draft, Submitted and Approved.

  1. Click Submit for Validation when the draft is ready. The task now shows Needs approval and appears in the Inbox.
  2. A project member reviews it and clicks Approve TSD.

Writing and approving it yourself? Save & Approve saves, submits and approves in one step.

Tick Start development run on approval before approving to start a run straight away. Otherwise, start it later from the Runs tab - see Runs.

Submitted and approved TSDs are read-only. The footer shows when it was submitted and approved.

An approved or submitted TSD opens as a Summary - the goal, the Acceptance criteria as a checklist, the risks and what was assumed (to confirm before approving) - with the full text below and the technical sections under Technical details. Compare with v… shows what changed since the previous version, and Download as Markdown saves the spec as a file to share. Under the review, the decisions you confirmed are listed, with how many questions are still open.

For a change people will see, let CodeLynq design the screens first: approving the TSD then approves the mockup shown, and the run builds to match it. See Mockups.

Request a change to a built task

When the task has an open pull request and you want something different, use Request a change on the task's Overview. Describe the change and click Work into the spec. On the Runs tab you can also tick feedback items and click Work into the spec as a change.

  1. The AI writes a new version of the TSD with the change worked in. A yellow block above the fields shows your request and What changes compared with what was built.
  2. Check the fields, tick Build the change on the existing branch and approve.
  3. A new run checks out the pull request's branch, builds the change on top of the work already there and pushes to the same branch. The open pull request is updated; no new one is opened.

On a self-hosted runner this needs runner 1.9.0 or newer. See Self-hosted runners.

Change an approved TSD

Click Create New Version on an approved TSD. This copies it into a new draft that you edit and approve as before. Earlier versions stay available from the version selector at the top of the Spec tab, with their dates.

Approve on the go

In the mobile app you can read the latest TSD of a task and approve it, with or without starting a run.

Tips

  • A good task description saves a round of corrections. Mention constraints and what is out of scope.
  • If the TSD misses context that applies to every task, add it to the project's context and conventions or codebase memory rather than correcting each spec.
  • Several branches? Check that the approach covers the differences between them. See Work on several branches at once.

Test it on a task from your own backlog

Send us one real task. We run CodeLynq on your repository and you review the pull request. Free, within 5 working days of approving the spec.