Client Upsale Proposal

An upsale proposal built on codebase evidence closes faster than one built on opinions. With Sun Agent Kit, you run a structured audit on the existing project, map the findings to business outcomes, validate claims with industry benchmarks, and produce a polished client-facing document — all without writing a single line of code. What used to take a senior engineer and an account manager most of a week is done by Wednesday afternoon.

Overview

Goal: Generate a structured upsale proposal backed by codebase evidence, not opinions
Time: 1–2 hours (vs 4–6 hours manual analysis + writing)
Agents used: scout, researcher, doc-writer
Commands: /sk:scout, /sk:brainstorm, /sk:research, /sk:plan, /sk:docs

Note: No code is written in this workflow. Every command produces analysis, research, or documentation — the codebase is read-only throughout.

Prerequisites

• Sun Agent Kit installed (installation guide)
• Access to the client’s codebase (local clone or read access is sufficient)
• A clear trigger for the upsale — a new client request, a support incident, an upcoming renewal
• Account manager context: what outcome does the client care about most? (performance, mobile, scale)

Step-by-Step Workflow

Step 1: Audit the Codebase for Evidence

/sk:scout "audit this Laravel codebase for technical debt, missing test coverage, architectural bottlenecks, security gaps, and scalability risks — generate a structured findings report for a client proposal"

What happens: The agent:

1. Traverses the repository and indexes source files, configuration, and dependency manifests
2. Measures test coverage, identifies missing test suites, and flags untested critical paths
3. Detects architectural patterns — or the absence of them — including missing service layers, tight coupling, and direct database calls in controllers
4. Scans for known security issues: exposed credentials, outdated packages, missing input validation
5. Saves a structured findings report to plans/reports/scout-report.md with severity ratings and evidence references

Step 2: Map Findings to Business Value

/sk:brainstorm "based on the scout findings: no tests, monolithic architecture, no API layer, and the client wants a mobile app — what are the 3-5 most compelling upsell scopes? Map each to both technical risk reduction and business value"

What happens: The agent:

1. Reads the scout report and extracts the highest-severity findings
2. Translates each technical finding into a business risk statement (e.g., “no test coverage → high regression risk during mobile API extraction”)
3. Groups findings into coherent engagement scopes, each with a clear value proposition
4. Ranks scopes by client impact and delivery feasibility
5. Produces a prioritized list of upsale angles with both technical justification and business framing

Step 3: Validate Claims with Industry Data

/sk:research "ROI benchmarks: cost of adding test coverage to a 50k LOC Laravel project, typical timeline for API extraction from a PHP monolith, mobile app backend requirements for REST vs GraphQL"

What happens: The agent:

1. Searches for industry benchmarks, case studies, and community data relevant to the proposed scopes
2. Finds effort estimates and timeline ranges for comparable engagements
3. Locates ROI data for test infrastructure investment in PHP/Laravel projects
4. Compiles a research summary with source references to support proposal claims
5. Flags any areas where benchmarks are sparse or estimates carry high variance

Step 4: Structure the Proposal Document

/sk:plan "structure a 3-month upsell proposal: Section 1 current state findings with evidence, Section 2 three engagement scopes with effort estimates, Section 3 risk-if-no-action analysis, Section 4 pricing tiers (essential/recommended/comprehensive)"

What happens: The agent:

1. Reads the scout report, brainstorm output, and research summary as inputs
2. Designs a proposal structure that leads with evidence and builds toward the ask
3. Defines what belongs in each section — which findings, which scopes, which benchmarks
4. Specifies the pricing tier model: what is included in each tier and how to differentiate them
5. Saves the document plan to plans/proposal-structure.md for the doc-writer to execute

Step 5: Write the Client-Facing Proposal

/sk:docs "write the upsell proposal document per the plan — formal client-facing tone, reference scout findings as supporting evidence, include executive summary at the top"

What happens: The agent:

1. Reads the proposal structure plan and all prior agent outputs as source material
2. Writes each section in formal client-facing language, targeting a non-technical executive audience
3. Embeds specific scout findings as supporting evidence — codebase statistics, not abstract claims
4. Builds three tiered engagement options with scope, timeline, and relative pricing guidance
5. Generates the final proposal document and saves it to docs/client-proposal.md

Complete Example: Turning a Mobile App Request into a 3-Month Engagement

Scenario: You’re maintaining a 2-year-old Laravel monolith for a client. The codebase has grown to ~50k lines with no test suite, no service layer, and all business logic living in Blade controllers. On a Monday call, the client mentions they want a mobile app by Q3. Your account manager asks for a proposal by end of week.

You run:

# 1. Audit the codebase — what does the evidence actually say?
/sk:scout "audit this Laravel codebase for technical debt, missing test coverage, architectural bottlenecks, security gaps, and scalability risks — generate a structured findings report for a client proposal"

# 2. Map the findings to upsale angles the account manager can pitch
/sk:brainstorm "based on the scout findings: no tests, monolithic architecture, no API layer, and the client wants a mobile app — what are the 3-5 most compelling upsell scopes? Map each to both technical risk reduction and business value"

# 3. Validate effort estimates and ROI claims before putting them in front of a client
/sk:research "ROI benchmarks: cost of adding test coverage to a 50k LOC Laravel project, typical timeline for API extraction from a PHP monolith, mobile app backend requirements for REST vs GraphQL"

# 4. Design the proposal structure before writing a word of prose
/sk:plan "structure a 3-month upsell proposal: Section 1 current state findings with evidence, Section 2 three engagement scopes with effort estimates, Section 3 risk-if-no-action analysis, Section 4 pricing tiers (essential/recommended/comprehensive)"

# 5. Write the final client-facing document
/sk:docs "write the upsell proposal document per the plan — formal client-facing tone, reference scout findings as supporting evidence, include executive summary at the top"

Result: By Wednesday afternoon, you have a 10-page proposal with codebase evidence, three tiered engagement options — test infrastructure, API layer extraction, and mobile app development — and ROI projections grounded in research. The account manager walks into the Friday client meeting with something credible, not a quote built on gut feeling.

Time Comparison

Best Practices

1. Ground every proposal claim in scout findings ✅

Clients trust evidence over opinions. When the proposal says “your codebase has zero test coverage across 47 controller classes,” that lands differently than “we think you need tests.” Scout findings are your credibility.

2. Offer tiered scopes ✅

Essential / Recommended / Comprehensive gives the client options instead of a take-it-or-leave-it price. Clients who would reject a single large scope often choose the middle tier when given a range.

3. Tell the docs prompt the audience and tone explicitly ✅

"formal client-facing tone" is not implied — state it in every /sk:docs call. The doc-writer defaults to a technical register if you don’t specify otherwise.

4. Include a “risk if no action” section ✅

Quantifying the cost of doing nothing is more persuasive than describing the benefit of acting. “Extracting the API layer now costs X; doing it after the mobile app launch costs 3X and requires a rewrite” is a concrete reason to decide.

5. Proposing work with no basis in the scout findings ❌

If the proposal recommends a Kubernetes migration but the scout report says nothing about infrastructure scaling issues, that scope has no evidence behind it. Clients and their technical advisors will notice, and it undermines the credibility of the entire document.

6. Skipping research ❌

Unverified ROI claims are worse than no claims. If you can’t back an effort estimate with a benchmark or a comparable case study, either remove it or flag it explicitly as an internal estimate.

Troubleshooting

Problem: Scout finds too many issues — the proposal reads like a bug report

Solution: Use brainstorm to prioritize before writing. Add a constraint to the brainstorm prompt: "pick the 3 most business-critical findings — ignore anything that is cosmetic or low risk". A proposal that tries to fix everything gets nothing approved.

Problem: Docs output is too technical for a non-technical CTO

Solution: Re-run /sk:docs with an explicit audience instruction: "write for a non-technical CTO who understands business risk but not PHP internals — no code snippets, no framework-specific terminology".

Problem: Plan generates too many proposal sections

Solution: Constrain the structure upfront: "maximum 4 sections, executive summary under 200 words, no appendices". More sections do not make a stronger proposal — they make it harder to approve.

Problem: Research returns no relevant benchmarks for your stack

Solution: Narrow the search scope: "Laravel-specific test coverage ROI case studies from teams between 5 and 20 engineers". Generic software benchmarks are less credible than stack-specific data; if none exist, the research agent will say so clearly.

Next Steps

• Rapid Prototyping — if the proposal is accepted, prototype the new features before full build commitment
• Project Migration — if the proposal includes a tech stack migration, use this workflow to plan and execute it
• Generate Documentation — generate handoff documentation for the expanded engagement once it kicks off
• Security Audit & Scan — when the proposal includes a security remediation scope, run a dedicated security scan as the first deliverable

Key takeaway: An upsale proposal backed by a codebase audit closes faster than one based on opinions — /sk:scout gives you the evidence, /sk:brainstorm maps it to business value, and /sk:docs turns it into a client-ready deliverable. No code written, no engineering time wasted on a proposal that might not land.