Medir antes de añadir otra capa
When this article first appeared, the project was still called Blupoli Puzzles. Today we call the product Blupoli Puzzles, but the phase described here still explains an important shift in how we work. During an expansion phase, progress is easy to point at: a new game appears, a category grows, a feature lands, a screen gains another capability. Each change is visible. The harder question arrives when speed itself makes the product difficult to see clearly: does everything we have built still feel like one coherent thing?
The audit began because the answer stopped being obvious. There was no single fire to put out. No spectacular bug explained the discomfort. Instead, many individually reasonable decisions were starting to produce friction when viewed together. One board had less room than another. A control moved between games. Light mode was better supported on some surfaces. One explanation assumed too much knowledge. The catalogue kept growing while discovery still behaved as if the collection were small.
This kind of debt rarely triggers an automatic alarm. The code compiles. Tests pass. A player can finish a session. Yet the product feels less deliberate than it should. The audit was our attempt to turn that fuzzy feeling into a map of work.
No bugs does not mean high quality
A team can have a short bug list and still accumulate significant product debt. The reason is simple: many sources of friction are not binary failures. A button that is slightly too far away is not “broken.” Weak onboarding does not throw an exception. A layout that feels cramped on a tablet may not block every session. A vague category label never crashes the app. All of these still increase the amount of work required from the user.
That difference forces a broader definition of quality. Rules must be correct and technical failures must be prevented, but we also need to examine comprehension, rhythm, accessibility, consistency, discovery, perceived performance and maintainability. Puzzle products add another dimension: a board can be mathematically valid and still be a poor experience if difficulty is meaningless, generation stalls or the interface fails to explain the first move.
The audit gave those concerns one shared place. Not because they all deserve equal priority, but because dependencies matter. A small system-level improvement can resolve issues across many screens. A visual inconsistency can reveal an architectural boundary in the wrong place.
Pausing expansion does not mean the expansion was a mistake
A consolidation phase can sound like a reaction against growth: “we added too much and now we have to clean it up.” Our interpretation was different. Expansion had done useful work. Building different mechanics taught us what the platform needed. A larger catalogue exposed the limits of navigation. Multiple themes revealed coupled styling. Heterogeneous engines showed which parts of the shell were actually shared.
The mistake would have been to keep using the same success metric after the context changed. Early phases can optimize for learning and coverage. Later phases need to consolidate those lessons. Treating both phases as if the priority were identical is how product debt becomes permanent.
So the pause was intentional. Before adding another large layer of functionality, we wanted to raise the floor: reduce needless exceptions, make recurring decisions consistent and turn discoveries into infrastructure.
A useful audit has to inspect several layers at once
Looking only at UI would have missed causes in data, engines and build tooling. Looking only at architecture would have missed real interaction friction. We ended up evaluating the product across multiple dimensions: user experience, interface, performance, architecture, content, discovery and the ability to scale.
For UX we asked whether the next action was clear and whether frequent tools sat where people expected. For UI we reviewed hierarchy, state, theme, spacing and responsive behavior. Architecture review looked for duplication, coupling and exceptions that made broad improvements hard to ship. Performance meant both load time and generators capable of blocking the browser. Content review covered rules, categories, copy and routes. Scalability asked a different question: how expensive will it be to repeat this improvement in six months?
The value of seeing these layers together was the ability to discover shared causes. Five symptoms across five games can come from one design decision. Fixing the cause has far more leverage than closing five isolated tickets.
The Sudoku laboratory gave us something concrete to compare against
Auditing without a reference can collapse into preference. “This should look better” or “this needs more breathing room” may be valid observations, but they are hard to prioritize when there is no shared idea of the experience we are aiming for. The earlier Sudoku work gave us one place where hierarchy, controls, onboarding, feedback and states had already been explored deeply.
We did not treat Sudoku as a visual template. We used it as contrast. If high-frequency actions were close to the board there, we could ask why they were distant elsewhere. If focus was visible, missing states became obvious. If the layout made the interactive area dominant, older pages that inherited a reading-width container looked suspicious.
The method is explained in the article about Sudoku as an interface laboratory. The important audit lesson is that a useful reference does not prescribe pixels; it exposes principles.
The shared system multiplied the return on each finding
The audit overlapped with the consolidation of our shared UI system. That changed the economics of fixes. A problem in a shared component could be corrected once and benefit many experiences. A local inconsistency forced a different question: should it stay local, or does it reveal an incomplete abstraction?
That distinction pushed base-layer problems ahead of isolated polish. Improving focus, theming, width, shell behavior or shared states often creates a larger product effect than perfecting one screen. Individual details still matter; the point is that system work can turn one improvement into inherited capability.
We started thinking about leverage alongside severity. A small issue in a shared layer may deserve attention before a more visible problem on a low-traffic surface if the fix raises the baseline of everything that comes after it.
Page width was a small example with a large lesson
Some boards were squeezed into a container that had originally made sense for reading. The rule was reasonable in the context where it was created, then accidentally became global. Some games fit. Others lost useful scale or became uncomfortable.
The correction required admitting that “shared layout” does not mean “identical width.” The platform needed different presentation contexts. This looked like a visual adjustment and confirmed an architectural point: a reusable rule should represent a real responsibility, not historical coincidence.
This is exactly what audits are good at. The first observation can be “the board is too small.” The cause may be “we are applying an editorial constraint to a game context.” The correct task is not simply to enlarge one page. It is to separate two needs.
Light mode became a detector for coupled styling
A second theme exposed values that looked harmless while everything lived on dark surfaces. Borders, shadows, selection colors and disabled states sometimes relied on one fixed contrast relationship. Theme review forced us to distinguish semantic colors from concrete values and to ask whether components actually shared a system.
Light mode therefore became more than a preference. It was an architecture test. If switching themes requires per-game exceptions, styling is probably too coupled. If an interaction state loses meaning when the background changes, semantics are still tied to appearance.
Tests like this are valuable because they surface debt before another requirement does. Interfaces that survive more than one theme are usually better prepared for branding changes, accessibility needs and future surfaces as well.
Responsive behavior and accessibility leave less room for hidden assumptions
A wide monitor and a mouse forgive a lot. Phones and keyboards do not. Tiny touch targets, overflowing content, hover-only controls, strange focus order and color-only states become obvious as soon as the interaction model changes.
That is why the audit included viewports and input methods. We did not want responsive design and accessibility to be columns at the end of a checklist. They are ways of stress-testing the system under conditions where implicit assumptions fail.
This pressure also connected directly to Android plans. As we explain in the article about Capacitor, reusing the web in a future app only makes sense if the mobile web is already strong. Auditing touch, layout and persistence improved today’s product and prepared any later client.
Performance also means the cost of change
Performance usually means load time, CPU and response latency. The audit added another dimension: how expensive is it to change the product? An architecture where a common improvement requires editing dozens of pages is slow even if Lighthouse scores are excellent. Duplicate taxonomy slows every decision. A control that has drifted across engines increases regression risk.
This “development performance” does not replace technical performance; it complements it. The platform needs to load quickly and also allow quality improvements to propagate safely. Both determine how fast the product can get better.
We therefore looked for repeated work that could become data, a component, a build step or a contract. Removing repetition saves time, but more importantly it reduces divergence.
Puzzle generation proved that correct is not necessarily good enough
Some of the most important debt lived inside games. A generator can produce a valid board and still create a poor experience. It may take too long, allow several solutions, repeat trivial structures or mistake board size for difficulty. Those problems are not always visible when a page first loads.
That is why technical audit had to go beyond presentation. Solvers, uniqueness checks, seeds, generation budgets and difficulty models are product-quality tools. The article “Generating a puzzle is not the same as solving one” explores that boundary in detail.
The connection matters: polishing a game card without reviewing the quality of the sessions behind it would be cosmetic. Consolidation means inspecting the whole chain—from discovery to whether the generated challenge deserves a player’s time.
The catalogue had to stop behaving like a list
As variety increases, a wall of cards stops being a useful discovery tool. Some people know they want Sudoku and search by name. Others want “something deductive” without knowing which title fits. Categories, filters, search and explanatory context become part of the product.
The audit made us ask whether catalogue information helped people choose. Did categories reflect mechanics? Did descriptions provide useful context? Did cards communicate anything beyond a name? Could someone explore without endless scrolling? Should competitive games live in the same discovery flow as single-solution puzzles?
These are not isolated feature questions. They require taxonomy, data and navigation to work together. Pausing expansion created room to improve a layer that raises the value of everything already in the catalogue.
An audit is useless if it ends as a giant document
It is easy to produce an excellent report and change nothing. To prevent that, every finding had to become executable work: a task with context, impact, dependencies and a definition of done. This translation forces precision. “Improve the UI” is not a useful task. “Separate editorial width from game-shell width and verify large boards on mobile” can be.
Granularity also matters when some implementation can be delegated to AI agents. Vague requests create broad, hard-to-review changes. A bounded task that explains the problem, intention and validation lets an agent be more autonomous without making review meaningless.
The audit therefore becomes a decision system rather than a snapshot: observe, prioritize, translate, implement, verify, close. Each step lowers the chance that the same finding will return months later as a surprise.
Prioritization means separating impact from novelty
Audit work competes with new ideas. New features are often more exciting because they create something visible. Fixing focus behavior or normalizing a container has less immediate glamour. We therefore needed priority criteria that did not depend on enthusiasm.
Cross-cutting impact, blockers, user risk, frequency and the cost of fixing something later all mattered. A base improvement that unlocks several future pieces can outrank an isolated feature. An accessibility problem may deserve priority even if it affects a smaller share of sessions. A minor cosmetic inconsistency can wait when it is not creating more debt.
Prioritization also means accepting that not everything gets fixed in the current phase. Auditing helps us see the whole system and decide what not to do yet. That explicit restraint protects attention.
Catalogue size stopped being a sufficient progress metric
Expansion phases naturally encourage simple numbers. But catalogue size loses usefulness when it does not distinguish state, quality or depth. A puzzle that exists in the repository may still be below the standard we want to recommend publicly.
This reflection later led to stricter rules around “available” versus “coming soon.” The follow-up article on quality before quantity develops that shift. The audit was the earlier step: we learned to see the catalogue as a set of experiences rather than a counter.
Once the metric changes, incentives change. Improving an existing game can be worth more than adding another. Closing system debt can create more value than increasing a public total. That transition is difficult precisely because progress becomes less photogenic and more structural.
An audit should verify that the architecture tells the truth
A platform can claim to have shared components while keeping divergent copies. It can call itself localized while hardcoded strings remain. It can claim theme support while some boards ignore the variables. A serious audit compares the technical story with the repository that actually ships.
That means looking for exceptions, not just the happy path: which games bypass the shell, which pages receive a different header, which assets still use old routes, which data is duplicated, which variants the tests really cover. Many later build scripts and quality gates grew from this habit.
Automating invariant checks preserves human attention. If a rule can be verified reliably by a machine, reviewers should not have to remember it manually in every pull request. Human review can focus on what machines still judge poorly: clarity, rhythm, ergonomics and the actual quality of a puzzle.
The goal was never zero debt
An audit becomes endless if perfection is the target. Every active product contains compromises, temporary decisions and known debt. Our real goal was to regain control: know which problems existed, which were deliberate, which had priority and which system changes would stop them from multiplying.
That distinction prevents consolidation from turning into a permanent pause. Once the foundation reaches a reasonable standard and the main causes of divergence are under control, expansion can resume from a stronger base. Auditing does not replace building. It improves the ability to build afterward.
Stopping was a way to accelerate the next stretch
From the outside, a week spent consolidating can look slower than a week that ships several new features. At the system level the opposite may be true. A component that removes future duplication, a layout change that fixes many pages or a taxonomy improvement that strengthens discovery can compound over time.
That compounding effect was the point. The first phase had proved we could build many things. The next needed to prove that those things could coexist and evolve without every new addition increasing disorder.
Blupoli Puzzles has changed since that audit, but we still use the same signal for knowing when to slow down: if adding one more thing makes the whole product harder to understand, it is time to inspect the system. Stopping the count is not abandoning momentum. Sometimes it is the only way to make sure speed is still pointed in the right direction.