# A Digital Transformation Starts With One Workflow Source: https://yiqilai.tech/notes/a-digital-transformation-starts-with-one-workflow.md Canonical: https://yiqilai.tech/notes/a-digital-transformation-starts-with-one-workflow Markdown: https://yiqilai.tech/notes/a-digital-transformation-starts-with-one-workflow.md Language: en Digital transformation is too often sold as a platform change. In practice, it usually starts with one workflow that people already care about. The best first workflow is not always the biggest. It is the one where the pain is visible, the owner is clear, and the improvement can be measured quickly. ## Start with the current path Before designing software, map how the work happens now: - who starts it - what information is needed - where delays appear - how decisions are recorded - what happens when something goes wrong This map is more valuable than a feature list. ## Replace friction, not people Good transformation respects the expertise already inside the team. The software should remove copying, waiting, searching, and re-entering data so people can spend more time on judgment. That distinction matters. Tools that ignore the existing workflow usually create a second system beside the first one. ## Measure one improvement Pick one number: - time from request to response - number of manual handoffs - missing information rate - days until a decision is recorded The number does not need to describe the whole business. It needs to prove that the first loop is better. ## Then expand Once one workflow improves, the next step becomes clearer. Transformation becomes a sequence of useful changes instead of a grand promise. --- # Agent Workflows Need Reviewable Context Source: https://yiqilai.tech/notes/agent-workflows-need-reviewable-context.md Canonical: https://yiqilai.tech/notes/agent-workflows-need-reviewable-context Markdown: https://yiqilai.tech/notes/agent-workflows-need-reviewable-context.md Language: en AI agents make software work faster, but speed is only useful when the work remains reviewable. The risky version of agentic development is not that an agent writes code. The risky version is that nobody can explain why the code changed. ## Context should be explicit Before an agent changes a system, it should know the goal, the files likely involved, the constraints, and the verification expected at the end. That context does not need to be long. It needs to be specific enough to prevent wandering. ## Small scopes protect quality An agent is more useful when the task has a boundary: - update this component - replace this content set - verify this interaction - fix this build error Broad tasks can still work, but they need stronger checkpoints. ## Review is part of the workflow The output should make review easier: - changed files - behavior changed - commands run - screenshots or route checks when visual work is involved - remaining risk Without that proof, speed becomes an illusion. ## Ownership stays human The agent can do the mechanical work. The team still owns the taste, the tradeoff, and the decision to ship. That is the healthy shape: faster execution, clearer review, no abdication. --- # AI Features Should Earn Their Place Source: https://yiqilai.tech/notes/ai-features-should-earn-their-place.md Canonical: https://yiqilai.tech/notes/ai-features-should-earn-their-place Markdown: https://yiqilai.tech/notes/ai-features-should-earn-their-place.md Language: en AI should not be added because a product needs an AI story. It should be added when it makes the user's judgment easier to apply. The best AI features do not replace responsibility. They compress the path between context and a better decision. ## A good AI feature has a job Useful AI features usually do one of four things: - summarize scattered context - draft a first version - compare options - automate a repeatable handoff If a feature cannot explain which job it does, it is probably just a button with a model behind it. ## The review moment matters Every AI workflow needs a clear review moment. The user should know what was produced, what evidence was used, and what still requires judgment. Without that, the feature becomes either magic or risk. Neither one is a durable product position. ## Context is the product The hard part is rarely the prompt. The hard part is assembling the right context without making the user babysit the system. That is why AI product work often looks like information architecture: naming things, preserving decisions, connecting records, and making outputs traceable. ## The test Ask a simple question: if the AI part disappeared, would the workflow still make sense? If the answer is no, the workflow may be too dependent on novelty. If the answer is yes, AI can become an accelerator instead of a crutch. --- # Start With the Smallest Valuable Loop Source: https://yiqilai.tech/notes/start-with-the-smallest-valuable-loop.md Canonical: https://yiqilai.tech/notes/start-with-the-smallest-valuable-loop Markdown: https://yiqilai.tech/notes/start-with-the-smallest-valuable-loop.md Language: en The first version of a product should prove one loop, not the whole vision. A loop has a user, an action, a result, and a reason to come back. If that loop is weak, adding more screens only gives the weakness more places to hide. ## A feature is not a loop A feature can exist without changing behavior. A loop has to move someone from intent to outcome. For example, "create a dashboard" is a feature. "A manager sees the three blocked projects before the Monday meeting" is a loop. The second one is easier to judge because it has a moment, a user, and a consequence. ## Useful beats complete Complete systems are expensive to build and expensive to change. Useful loops are easier to test. The first question is not "What can this become?" The first question is "What is the smallest thing that would be missed if it disappeared tomorrow?" ## What to cut Cut anything that does not help the loop finish: - settings that only serve future edge cases - dashboards without a recurring decision - onboarding copy that explains features the user cannot use yet - integrations before the core workflow works manually ## What to keep Keep the parts that create proof: a real input, a real output, a real review point, and a real user who cares. Once the loop works, expansion becomes safer. The product has a center. --- # TypeScript Boundaries That Lower Maintenance Source: https://yiqilai.tech/notes/typescript-boundaries-that-lower-maintenance.md Canonical: https://yiqilai.tech/notes/typescript-boundaries-that-lower-maintenance Markdown: https://yiqilai.tech/notes/typescript-boundaries-that-lower-maintenance.md Language: en TypeScript is most valuable when it describes boundaries, not when it decorates every line. In a multi-site workspace, the boundary is the product. Apps need freedom to express their own content. Shared packages need discipline so one site's assumption does not leak into another site's runtime. ## Types should name contracts The most useful types answer questions: - What does a Note need to render everywhere? - Which fields are optional presentation details? - What categories are allowed? - What can a shared component assume? These are product questions disguised as engineering questions. ## Keep local things local If a component only belongs to one app, it should stay in that app. Moving it into a shared package too early creates a false promise: that the abstraction is ready for reuse. Shared code should be earned by repeated use. ## Avoid clever data Stringly data is easy to start and hard to maintain. A fixed category list is less flexible, but it makes navigation, routes, labels, and RSS output easier to reason about. The goal is not maximum configurability. The goal is fewer surprises when a new note or page is added. ## Boring is a feature Good boundaries are boring. They make the next change feel obvious. That is what maintainability usually means: the system tells you where the work belongs.