Lessons Learned
Lessons Learned: Bilko
Project: Bilko — Balkan Accounting SaaS
Version: 0.1
Date: 2026-02-23
Author: John (AI Director)
Status: Draft
Reviewers: Alem Bašić (CEO)
Document History
| Version |
Date |
Author |
Changes |
| 0.1 |
2026-02-23 |
John (AI Director) |
Initial entry — Phase 1 kickoff learnings |
"Lessons learned without behavior change is not learning." — Alem Bašić, 2026-02-13 (ZAKON #0)
Every entry in this log must produce either a systemic fix (hook/tool/rule) or a concrete behavior change. Observations without action items do not belong here.
| Field |
Value |
| Session Type |
Phase Review (after Pipeline Gate 8 pass + initial build) |
| Project |
Bilko |
| Phase / Sprint |
Pre-Sprint 1 — Phase 1 kickoff |
| Period Covered |
2026-02-19 – 2026-02-23 |
| Facilitator |
John (AI Director) |
| Participants |
John, Alem Bašić |
| Date of Session |
2026-02-23 |
| Duration |
Retrospective of first 4 days |
2. What Went Well (Keep Doing)
| # |
What Went Well |
Why It Worked |
How to Preserve |
Category |
| KD-01 |
8-gate pipeline forced all critical research before coding began |
Gates prevented building on wrong assumptions; regulatory research (MULTI-REGION-OVERVIEW.md) was detailed and accurate |
Continue using pipeline gates for Phase 2 (Croatia) and Phase 3 (BiH); enforce gate passage before any new country's features |
Process |
| KD-02 |
Database schema (15 models) designed before writing any application code |
Schema aligned with accounting law requirements (double-entry, NUMERIC, audit trail) from day 1; no retroactive migrations |
Always design data model first for financial features; NEVER write API code against an undefined schema |
Technical |
| KD-03 |
NUMERIC(19,4) for all monetary fields decided upfront and enforced in schema |
Prevented entire class of floating-point accounting errors; found in Fiken research |
CI test: fail if any new field for monetary values uses Float/Decimal without explicit 4dp precision; document in CLAUDE.md |
Technical |
| KD-04 |
Regulatory research completed and documented before building |
SEF API requirements, PDV rates, Croatian eRačun timing — all known before design phase |
Research-first mandate in project charter; Asmir as ongoing regulatory advisor |
Process |
| KD-05 |
CEO approval gate (Gate 8) prevents building orphaned features |
Alem reviewed full plan before code was written; GO decision is documented and traceable |
Maintain Gate 8 for each major phase/country expansion |
Process |
Highlights
KD-02 Detail:
The decision to define all 15 Prisma models (Organization, User, Invoice, InvoiceItem, Transaction, etc.) before writing a single API endpoint proved to be the most valuable architectural decision of Phase 1. When the backend starts being built, the developer (human or AI) has a complete, validated schema to work against — no guessing about data shapes. The schema covers double-entry (debitAccountId + creditAccountId in Transaction), multi-currency (ExchangeRate model with locked rates), and audit trail (LoggedAction append-only). This pattern should be standard for all future Bilko features.
3. What Didn't Go Well (Stop Doing)
| # |
What Didn't Work |
Root Cause |
Impact (1-10) |
Action Item |
Owner |
Deadline |
| SD-01 |
Frontend built entirely with mock data — 8 pages, zero real API connections |
Prototype-speed MVP prioritized demo-ability over production-readiness; no explicit decision to replace mock data before launch |
10 |
CI check: grep for mock-data.ts imports outside test files; fail build in staging/production |
John |
Sprint 1 |
| SD-02 |
packages/ui component library left empty — all components in apps/web, creating future duplication risk |
"We'll extract later" reasoning; never happened during MVP build |
4 |
Document as TD-003; schedule for Phase 2 before mobile work starts |
John |
2026-05-01 |
| SD-03 |
No CI/CD pipeline established before writing application code |
Infrastructure "can wait" assumption; now blocking safe iteration |
8 |
CI/CD setup is Sprint 1 task 1 before any API endpoints |
John |
2026-03-07 |
| SD-04 |
API-REFERENCE.md not created alongside the schema and routes structure |
Documentation always deferred in early phases; creates frontend/backend misalignment |
5 |
Every new API endpoint must have its Request/Response schema documented in API-REFERENCE.md in the same PR |
John |
Ongoing |
| SD-05 |
No unit tests written during MVP build |
Speed prioritized; tests "added later" — never happened |
9 |
Test must be written in the same sprint as the feature, not deferred |
John |
Ongoing |
Root Cause Analysis — Deep Dives
SD-01: Mock Data Throughout Frontend
Problem: All 8 frontend pages show hardcoded mock data. Beta testers would see fake numbers. Cannot test real API integration.
5 Whys:
- Why is all data mocked? → Frontend was built as a prototype to show design/flow, not as production code
- Why was it built as prototype only? → Gate 8 (CEO approval) was needed before real backend investment; prototype reduced risk
- Why wasn't mock replacement scheduled explicitly? → The PIPELINE.md "Next Steps" listed it but no MC task was created with a deadline
- Why was no MC task created? → Prototype phase didn't have sprint planning; items added to informal list
- Why did informal list not get actioned? → No hook or gate enforcing the replacement before beta access
Root Cause: No automated enforcement that mock data must be replaced before staging deployment.
Systemic Fix: CI check in apps/api/src/ and apps/web/ — grep for mock-data.ts imports outside /test/ directories; fail build if found in staging/production environment. Add to .github/workflows/ci.yml.
Ljestvica Fikseva (ZAKON #1): Hook > Tool > Rule > CLAUDE.md > Memory → Using CI hook (strongest enforcement)
SD-05: No Tests Written During MVP Build
Problem: 0% test coverage on financial logic (PDV, double-entry, SEF). Accounting software without tests is a liability — a PDV calculation bug could cause users to file incorrect tax returns.
5 Whys:
- Why are there no tests? → They were "deferred" to after the feature was "working"
- Why were they deferred? → Speed pressure to show CEO a working prototype
- Why did "working" not include tests? → No definition of "done" included test coverage
- Why was there no DoD? → Project was in prototype phase with informal standards
- Why were informal standards accepted? → No enforcement mechanism (no CI, no PR gate)
Root Cause: No CI gate requiring tests before merge; no DoD including test coverage.
Systemic Fix: GitHub Actions CI: npm test -- --coverage --coverageThreshold='{"global":{"lines":80}}' — fails PR if coverage below 80% overall or below 95% for src/services/ (financial logic). This is non-negotiable before Sprint 2 merges.
Ljestvica Fikseva: CI coverage gate → fails PR merge.
4. What to Try Next (Start Doing)
| # |
What to Try |
Expected Benefit |
Hypothesis |
Success Metric |
Trial Period |
| ST-01 |
Write tests FIRST (TDD) for financial logic (PDV, double-entry, SEF) |
Catches accounting bugs before they reach users; forces clear spec before coding |
If we write Given/When/Then tests for PDV calculation before writing the calculation, then PDV accuracy errors drop to 0 |
Zero PDV calculation bugs in beta; CI balance check passes 100% |
Sprint 2-4 |
| ST-02 |
Create API-REFERENCE.md endpoint-by-endpoint alongside backend implementation |
Eliminates frontend/backend sync issues; enables frontend developer (or agent) to start immediately |
If every endpoint has documented Request/Response before frontend implements it, then integration time drops 50% |
Zero "unexpected API shape" issues during frontend-backend connection sprint |
Sprint 2 |
| ST-03 |
SEF sandbox test on every PR touching invoice logic |
Catches SEF breaking changes before they reach production users |
If we run SEF sandbox test in CI for every invoice change, then SEF regression bugs = 0 in production |
Zero SEF regressions post-launch |
Sprint 3 (when SEF built) |
5. Key Findings by Category
5.1 Technical Findings
| # |
Finding |
Impact |
Recommendation |
| TF-01 |
Prisma's Decimal type maps cleanly to NUMERIC(19,4) — zero extra work for financial precision |
High positive |
Continue using Decimal for all monetary Prisma fields; never use Float |
| TF-02 |
LoggedAction as append-only audit table is a strong pattern — enforces immutability at schema level |
High positive |
Apply same pattern to other sensitive tables in future products (Drop, BasicFakta) |
| TF-03 |
Turborepo monorepo structure enables shared packages (database, ui) but requires discipline — empty packages create confusion |
Medium |
Either fill packages immediately or don't create them; no empty scaffolds |
| TF-04 |
Next.js 15 App Router + React Server Components significantly changes how data fetching works — team must understand before building |
High |
Document RSC vs client component decision boundary in CLAUDE.md |
Technical Patterns Observed:
- "Schema first, endpoints second, frontend third" — the correct build order for financial software; schema ensures all features are feasible
- Monorepo shared packages need a charter: what goes in packages/ui, what stays in apps/web — decide before Sprint 2
5.2 Process Findings
| # |
Finding |
Root Cause |
Recommendation |
| PF-01 |
8-gate pipeline prevented scope creep effectively — every decision was documented before coding |
Explicit gate criteria with documented evidence |
Apply same pipeline to Croatia (Phase 2) and BiH (Phase 3); don't skip gates even if process feels familiar |
| PF-02 |
"Next Steps" in PIPELINE.md without MC tasks = invisible work |
No translation from documentation to task management |
Every "Next Step" in any doc must have a corresponding MC task created immediately |
| PF-03 |
Prototype → production transition requires explicit decision and enforcement, not assumption |
Prototype mode is sticky — it continues until something forces a change |
Launch gate checklist must include "zero mock data imports verified by CI" |
Process Patterns Observed:
- Documentation-first works for planning but requires enforcement mechanisms to drive action
- Sprint planning discipline is critical even for AI-only teams — without sprints, work becomes unordered
5.3 Communication Findings
| # |
Finding |
Stakeholder Impact |
Recommendation |
| CF-01 |
Weekly Slack summary to Alem keeps CEO aligned without overhead meetings |
Alem can make informed go/no-go decisions asynchronously |
Maintain weekly sprint summary format from Communication Plan |
| CF-02 |
Regulatory questions need Asmir's input — cannot be resolved by research alone |
Wrong SEF implementation would cause launch failure |
Asmir review at every SEF-touching sprint; not just at start |
| # |
Finding |
Impact |
Recommendation |
| IF-01 |
No CI/CD pipeline means every deploy is a manual risk |
High — production incidents have no automated safety net |
CI/CD is Sprint 1 task 1, not an afterthought |
| IF-02 |
SEF sandbox environment must be set up before SEF integration sprint begins |
Medium — delay if sandbox access not ready |
Alem/Asmir to secure SEF sandbox credentials by 2026-03-01 |
5.5 Team & Collaboration Findings
| # |
Finding |
Impact |
Recommendation |
| TM-01 |
AI agent team (John + builder/validator agents) works well for structured implementation tasks but requires extremely detailed specs — vague requirements produce vague code |
High |
Every FR must have explicit Acceptance Criteria before being assigned to a builder agent |
| TM-02 |
Financial domain requires accounting expertise that pure coding agents don't have — PDV, double-entry, SEF need validation by someone who knows the law |
Critical |
Asmir review for all regulatory features; automated accounting logic tests are the safety net |
6. Action Items
| # |
Action Item |
Category |
Owner |
Sprint / Deadline |
Priority |
Status |
| AI-01 |
Set up CI/CD pipeline (GitHub Actions) — include: lint, type-check, tests, coverage gate, mock-data import check |
Infrastructure |
John |
Sprint 1 (by 2026-03-07) |
P1 |
Open |
| AI-02 |
Write unit tests for tax.service.ts (PDV calculation) as first test file — TDD model |
Testing |
builder agent |
Sprint 2 start (2026-03-07) |
P1 |
Open |
| AI-03 |
Create apps/api/docs/API-REFERENCE.md — document every endpoint as it is built |
Documentation |
John |
Ongoing from Sprint 1 |
P2 |
Open |
| AI-04 |
Add CI check: grep for mock-data.ts in non-test files — fail build if found in staging env |
Tools/Infrastructure |
John |
Sprint 1 (by 2026-03-07) |
P1 |
Open |
| AI-05 |
Secure SEF sandbox credentials from APR via Asmir |
Regulatory |
Alem + Asmir |
By 2026-03-01 |
P1 |
Open |
| AI-06 |
Create MC tasks for every "Next Step" in PIPELINE.md |
Process |
John |
Now |
P2 |
Open |
| AI-07 |
Asmir to review SEF integration design before Sprint 3 implementation |
Regulatory |
John |
By 2026-03-14 |
P1 |
Open |
| AI-08 |
Define RSC vs client component decision boundary for Bilko in CLAUDE.md |
Technical |
John |
Sprint 1 |
P2 |
Open |
7. Metrics Comparison — Planned vs. Actual
7.1 Timeline (Phase 1 kickoff only)
| Milestone |
Planned |
Actual |
Variance |
Root Cause |
| All 8 pipeline gates |
2026-02-19 |
2026-02-20 |
+1 day |
Gate 5-8 validation took longer than expected; thorough — good |
| Backend foundation (auth, 4 endpoints) |
2026-02-20 |
2026-02-20 |
0 |
On target |
| Full 50 endpoints |
2026-03-07 |
TBD |
TBD |
Sprint 1 |
7.2 Budget (Phase 1 so far)
| Category |
Planned (EUR) |
Actual (EUR) |
Variance |
Notes |
| Research + design + schema |
~€1,500 |
~€800 |
-€700 |
AI-assisted research more efficient than estimated |
| Backend foundation (auth) |
~€500 |
~€300 |
-€200 |
4 endpoints in 1 session |
| Running total |
~€2,000 |
~€1,100 |
-€900 |
Under budget so far |
7.3 Quality
| Metric |
Target |
Actual |
Status |
| Test coverage |
≥ 80% |
0% (not yet written) |
❌ In progress |
| Critical bugs at this stage |
0 |
0 |
✅ |
| Pipeline gate pass rate |
8/8 |
8/8 |
✅ |
| Database schema completeness |
15 models |
15 models |
✅ |
8. Recommendations for Future Projects
| # |
Recommendation |
Category |
Confidence |
Applicable When |
| REC-01 |
Define all database models before writing any API endpoints or frontend code |
Technical |
High |
Any data-driven application; especially financial |
| REC-02 |
Use pipeline gates (8-gate or adapted) before investing in build phase for any new product |
Process |
High |
All new ALAI products |
| REC-03 |
Set up CI/CD in Day 1 of Sprint 1 — never defer infrastructure; it becomes load-bearing |
Technical |
High |
Every project |
| REC-04 |
For regulated domains (accounting, finance, health): TDD is not optional; tests are the compliance proof |
Technical |
High |
Any compliance-regulated feature |
| REC-05 |
Research regulatory requirements with a local expert (Asmir for Balkans) before designing features that touch them |
Process |
High |
Any Balkan market expansion |
Top 3 Most Important Learnings
-
Schema First, Always: The 15-model Prisma schema designed before writing a single line of application code is why Bilko's data architecture is sound. The schema was validated against accounting law (double-entry), PRD features, and multi-currency requirements all at once. Future features should follow the same discipline: design the data model, get it reviewed, then build.
-
Mock Data Is a Prototype Trap: Shipping a frontend with mock data creates a false sense of completeness. The 8 pages look done but nothing works end-to-end. In future builds: either build frontend and backend in parallel (stub real API from day 1), or explicitly schedule "replace mock with real" as a first-class sprint task with CI enforcement.
-
Regulatory Compliance Is Not a Sprint Task — It's an Ongoing Advisor Relationship: SEF is not just "call an API." It's a living government system with evolving requirements, certificate requirements, and edge cases that only practitioners know. Asmir's involvement is not optional — it's risk mitigation. Budget time for regulatory review at every sprint touching financial compliance.
9. Knowledge Base Contribution
| Finding |
Contribution Type |
Target System |
Status |
Owner |
| NUMERIC(19,4) for all monetary fields |
Rule added to Bilko CLAUDE.md |
~/ALAI/products/Bilko/CLAUDE.md |
Done (already in CLAUDE.md) |
John |
| Pipeline gate process |
Template |
~/ALAI/products/Bilko/PIPELINE.md |
Done |
John |
| Mock data replacement pattern |
HiveMind entry |
HiveMind |
Open |
John |
| Schema-first pattern |
HiveMind entry |
HiveMind |
Open |
John |
HiveMind entries to add:
node ~/system/agents/hivemind/hivemind.js post "Bilko pattern: Always design Prisma schema before API endpoints. Schema = contract. Validated against accounting law + PRD features before writing any code."
node ~/system/agents/hivemind/hivemind.js post "Bilko lesson: Mock data in frontend is a prototype trap. Enforce removal with CI grep check before staging deployment. See CROSS-CUTTING/tech-debt-log.md TD-001."
Approval
| Role |
Name |
Date |
Signature |
| Author |
John (AI Director) |
2026-02-23 |
|
| Reviewer |
|
|
|
| Project Manager |
John |
2026-02-23 |
|
| AI Director (John) |
John |
2026-02-23 |
|
| Team |
Alem Bašić |
|
|
No comments to display
No comments to display