SiteSpruce

A lot of websites aren't really broken. They work. But over time, copy gets added, priorities change, different people make different decisions, and eventually the site doesn't quite reflect the business anymore.

Audit tools can point out individual problems, but a list of warnings only gets you so far. It doesn't tell you which things are connected, what actually matters, or whether you need a few targeted changes or something much bigger.

And without that context, it's very easy to jump straight to rewriting the copy, redesigning the site or rebuilding it.

SiteSpruce started from a different question:

What is the website actually doing now — and what needs to change?

The point wasn't to find as many problems as possible. It was to work out what was worth fixing, what could wait, and what kind of change the evidence actually supported.

The first version of SiteSpruce was a broad, hands-on website diagnostic consultancy.

I combined automated checks with detailed manual review across technical performance, mobile usability, user experience and design, SEO foundations, trust and credibility, and content and local visibility.

A finding on its own usually wasn't the interesting part. The useful bit was seeing when several apparently separate problems pointed to the same underlying issue, then working out what mattered most and what kind of change it actually called for.

The reports weren't implementation plans. They were there to help clients work out what to tackle first, what could wait, and whether the site needed targeted improvements or something larger.

I developed and refined the methodology through paid consultancy work. The self-service product came later.

I didn't want V2 to pretend it could reproduce the whole consultancy. V1 covered too many different areas and relied too much on broad manual review and judgment for that to make sense.

So I narrowed it to one part that was useful, repeatable and suited to a self-service product:

the gap between what a business wants to communicate, what its website actually communicates and what a first-time visitor is likely to take from it.

That became V2.

It focuses on what visitors understand, what they are still left wondering, where confidence drops and what deserves attention first.

AI made the repeated reading, comparison and interpretation practical at this scale. But I chose the scope around what the product could actually support with evidence, rather than around everything the technology could potentially do.

A self-service diagnostic has an awkward trust problem: the customer shouldn't have to pay before knowing whether SiteSpruce can actually review their website.

So the flow starts with a free check.

The customer enters their URL and three pieces of context: what the business does, who it is for and what the website should achieve.

Those answers are part of the analysis, not just setup. They give SiteSpruce the business-intent side of the comparison, so the customer can review and sharpen them before the full report runs.

SiteSpruce checks whether the site can be read and finds useful pages. If it can't, the flow stops before payment.

If it can, the customer sees the pages that were found and gets a limited observation from the homepage before choosing whether to continue.

After payment, the full review runs in the background across up to five useful pages, validates the findings and produces the finished report in the browser and as a PDF.

Salonix is a public demo site used to test SiteSpruce V2 end-to-end — the content and contact details shown are placeholders, not a real client.

I could have sent the website and questionnaire through one large prompt, but that would have made the output much harder to inspect, constrain or recover when something failed.

Instead, I split the analysis into stages with different jobs. The full product flow starts with the customer context and free preflight; after payment, the main analysis runs through these six stages.

The model is useful for the parts that need interpretation. I didn't want it controlling the workflow around them.

The boundary is fairly simple:

Software controls what evidence is available and whether the pipeline can continue. The model interprets that evidence and helps explain what it means for a first-time visitor.

Even the final writing stage cannot quietly redefine the diagnosis.

The overall assessment is chosen earlier in the conclusions stage and enforced by the application when the report is generated. A later writing call can't turn a Refinement into a Reposition just because it happens to produce different prose.

Page discovery follows the same rule. Common pages are matched deterministically; if there are still gaps, the model can classify links that actually exist on the site. Software validates the result and won't allow an invented URL to be crawled.

A detailed prompt doesn't make model output reliable. Structured output can be malformed, a finding can sound convincing without being well supported, and two stages can contradict each other. External services can also fail halfway through a run.

I treated those as normal failure modes the product had to handle, rather than unusual exceptions.

Model responses are validated against schemas before they become pipeline state. Invalid structured output can be corrected or retried instead of being silently accepted.

Findings also have to trace back to evidence collected from the website. SiteSpruce distinguishes between pages that do not exist and pages that could not be crawled, checks for unsupported or contradictory findings, and does not turn known gaps in coverage into confident conclusions.

Website and questionnaire content is treated as untrusted data, not as instructions to the model. It is fenced separately from the task instructions, with safeguards to stop content from escaping those boundaries and changing how the pipeline is supposed to behave.

Model-based validation is only one part of the check. Mechanical rules run alongside it, so the pipeline does not rely on the model to decide whether its own output is acceptable.

Validation can retry and, if needed, regenerate the visitor conclusions once. If the result still fails, the report is paused rather than sent. SiteSpruce gets an operational alert, while the completed stages stay saved so a recovery does not have to start from scratch.

The same idea applies to smaller features too. The free homepage preview is deliberately non-critical: if that model call fails, a successful site check can still continue rather than turning a preview feature into a system-wide failure.

Before I got to prompts, I had to decide what SiteSpruce would and wouldn't claim, what counted as enough evidence, and when the system should stop rather than force an answer.

I built the product around three perspectives: what the business intends to communicate, what the website actually shows and what a first-time visitor is likely to conclude.

That meant deciding:

Models can analyse the material and write explanations. They don't decide what SiteSpruce should claim, what counts as enough evidence or when an answer is too uncertain to send.

The same boundary applies commercially. SiteSpruce diagnoses; it doesn't sell the redesign or development work that might follow. The report is there to help the customer decide what to do next, not to create implementation work for SiteSpruce.

V2 turns one part of the original consultancy into an end-to-end self-service product.

At publication, it runs from the free website check through payment, background analysis and validation to the finished browser report, downloadable PDF and email delivery.

The workflow is implemented end to end, including crawling, persisted stage state, payment handling, report generation, quality checks, recovery paths and operational alerts. The repository also includes integration coverage for the main flow, duplicate payment/start behaviour and stage-level recovery.

That's the next thing I want to learn: where the reports consistently help, where the methodology needs tuning across different kinds of business, how often uncertainty or failure paths show up in production, and whether the product still holds up across a wider range of real websites.

Until I have that evidence, I'm keeping the claims here to what I can actually verify: what the product does, how it is built and what I still need to learn from its use.

SiteSpruce started with a broad human workflow. V2 got better when I stopped trying to reproduce all of it.

Once the scope was smaller, the architecture became clearer too: collect the evidence, structure it, interpret it, validate it, then explain it.

Each stage has a specific job, and no single model call gets to own the answer.

V2 is intentionally smaller than the original consultancy, but it has a clearer purpose, clearer failure boundaries and a scope I can actually support with evidence.