COS / Field guide
UX research questionnaire
Understand the code. Connect the decisions.
A shared map of software architecture, ownership and dependencies — from business domains down to individual fields.
Capabilities & value
Working today: interactive navigation and deterministic analysis of a fictional sample. Connecting and analyzing real repositories is future work.
| Capability | Pain point | What you can do | Expected value | Demo example | Evidence / limits |
|---|---|---|---|---|---|
| Whole-codebase map | Knowledge is scattered across teams | See domains, systems, services and code together | Build a shared understanding | Rings → Order Service | Modeled sample; no repository ingestion |
| Detailed inspection | Finding the relevant code takes time | Inspect contracts, fields, functions and source excerpts | Narrow a change investigation | Order contract → customer_id | Excerpts, not full source analysis |
| Dependency discovery | It is unclear what calls or consumes something | Follow callers, consumers, events and data access | Identify who should review a change | Upstream / downstream trace | Only explicitly modeled relationships |
| Business journeys | Business outcomes span many applications | Highlight checkout, fraud and reporting participants | Connect technical decisions to a business flow | Revenue reporting slice | Sample journey, not a live trace |
| Ownership | Finding the responsible team delays decisions | See named owners alongside dependencies | Coordinate reviews across teams | Orders → Trust → Data Platform | Fictional team assignments |
| Change simulation | A small field change can affect distant consumers | Compare breaking, review and unaffected consumers | Structure a change discussion | Rename customer_id; review owners | Deterministic scenarios, not compiler proof |
A six-step demo
1Overview2Business journey3Owner & dependencies4Field & source5Simulate change6Reset
Who is it for?
| User archetype | Responsibility | Typical question | Useful views / features | Decision or outcome |
|---|---|---|---|---|
| Software engineer / team lead | Builds and maintains software | What calls this code, and what must I update? | Functions, source, dependencies, simulation | Scope implementation and reviewers |
| Architect / platform lead | Coordinates how systems fit together | Which boundaries are bypassed or tightly connected? | Rings, architecture, undeclared read | Discuss boundaries and modernization sequence |
| CIO — chief information officer | Oversees technology operations and business alignment | Which systems and teams support a critical business process? | Domains, journeys, ownership | Discuss portfolio dependencies and delivery coordination |
| CTO — chief technology officer | Leads technology strategy and engineering | Where could a change spread across our platform? | Service landscape, contracts, impact | Prioritize engineering investigation and investment |
| CISO — chief information security officer | Leads information security and risk management | Where is sensitive data accessed outside intended boundaries? | Data reads, owners, sample undeclared dependencies | Choose investigation and review priorities; not a compliance verdict |
| Strategy / innovation leader | Coordinates transformation and new capabilities | What existing capabilities could constrain a new initiative? | Domains, systems, business journeys | Explore feasibility and cross-team involvement |
| Data leader | Owns data quality, reporting and data products | Which consumers rely on this field or unit? | Contracts, revenue slice, impact reasons | Coordinate schema and reporting changes |
Where does it fit?
Employee bands are illustrative. Architectural complexity and cross-team dependencies matter more than headcount.
| Company size / context | Team structure | Typical challenge | Fit | Prerequisites / limitations |
|---|---|---|---|---|
| Small · roughly 1–50 employees | One team, one simple application | Keeping knowledge current | Limited if the codebase is simple | A diagram and source search may be sufficient |
| Growing · roughly 50–250 | Several teams and shared services | Ownership gaps and cross-team changes | Useful as dependencies multiply | Needs a maintained map and reliable ownership |
| Mid-sized · roughly 250–2,000 | Multiple product, platform and data teams | Legacy integration and modernization coordination | Strong contextual fit | Real use would require repository ingestion and evidence validation |
| Large enterprise · roughly 2,000+ | Business units, shared platforms, distributed ownership | Portfolio complexity, change risk and fragmented knowledge | Strong need; production fit must be evaluated | Scale, access control, coverage and governance are not tested by this prototype |
What this demo does not prove
No repository is connected. Source excerpts, owners, undeclared reads and change results are modeled examples — not live telemetry, compiler verification or security certification.
Engineers, CIOs, CTOs, CISOs: jobs, pain points and workarounds
Ask for recent real examples. Follow up with “What happened next?”, “Can you show me?”, “How did you know?”.
Typical questions you ask yourself
- When you open an unfamiliar part of the codebase, what are the first three questions in your head?
- Engineers: “What calls this, who owns it, what breaks if I change it?” — which of these do you ask most, and how do you answer them today?
- CIO / CTO / CISO: which questions about systems, risk or ownership do you get asked that you cannot answer quickly?
- Walk me through your thought process the last time you had to decide whether a change was safe.
Frequent actions, activities, platforms and tools
- Which tasks around understanding or managing the codebase do you do every week?
- Which tools do you use for them (IDE search, Git hosting, diagram tools, wikis, APM, CMDB, spreadsheets, people)?
- Which of these tasks are repetitive, tedious or time-consuming? Roughly how long do they take and how often?
How you conduct a specific task
- Show me how you last traced a dependency or impact of a change — step by step.
- How do you onboard someone into a system, or prepare an architecture review or audit?
- How do you know when an investigation is complete and trustworthy?
Pain points and constraints
- Where does the process slow down, become uncertain or depend on one expert?
- Tell me about a recent incident or change that surprised you because of a hidden dependency.
- What constraints (security, access, compliance, budget, legacy tech) limit how you work?
- Which pain point would you most like solved now, and why is it more urgent than others?
Workarounds
- What do you do when documentation or tooling cannot answer your question?
- Which scripts, spreadsheets, diagrams or rituals have you built to fill the gap? How do you keep them up to date?
- What does the workaround cost you in time, risk or attention?
Dream solution and existing alternatives
- If you had a perfect tool for understanding and changing your architecture, what would it do on day one?
- Which products have you tried or evaluated? What was too expensive, too generic, or missing a key capability?
- What evidence would you need before trusting a dependency map or change-impact result?
- Who would evaluate, approve and pay for such a tool, and what criteria matter to each?