opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/small-business/skills/small-business-proposal-builder/reference/discovery_extraction.md

@@ -0,0 +1,138 @@
+# Discovery Extraction
+
+Discovery arrives in whatever form the owner could capture between jobs. Every one of these is a normal input, not a degraded one.
+
+The output of this step is always the same structure, regardless of what came in:
+
+```
+Customer:      <who, and who signs>
+Wants:         <the job, in their words>
+Scope, clear:  <what is definitely in>
+Scope, fuzzy:  <what is implied but not stated>
+Constraints:   <access, timing, code, site conditions>
+Out of scope:  <anything explicitly excluded>
+Dates:         <deadlines, start windows>
+Budget signal: <anything said about money>
+Gaps:          <what is missing and would change the price>
+```
+
+The Gaps line is the one that protects the owner. Everything else describes the job; that line describes what could go wrong.
+
+---
+
+## Call and meeting transcripts
+
+The richest input. Read the whole thing — the useful details are usually in the middle, not the summary.
+
+**Zoom's limits, so a missing transcript is not mistaken for an empty call.** It is read-only.
+It only reaches meetings the owner hosted or attended. And a recordings list covers a
+one-month range per call, so history older than that needs a second, earlier request. When a
+meeting is not reachable, say which one and ask the owner for the recording or their notes —
+never build a proposal on a call you could not read.
+
+Look for:
+
+- **Direct quotes about what they want.** Use their words in the proposal. Customers recognize their own phrasing and it signals they were heard.
+- **Constraints mentioned in passing.** "We can only get in after 6" is a cost driver that never appears in a scope list.
+- **Who actually decides.** "I'll need to run it by the board" changes the timeline and the follow-up.
+- **Budget signals.** "Last time we paid around 8" is the most valuable sentence in the transcript.
+- **What they complained about with their last vendor.** That is what the proposal should quietly address.
+
+---
+
+## Voice memos
+
+Recorded in a truck, often mid-thought, often with detail nobody would write down.
+
+Treat interruptions and self-corrections as real. If the owner says "call it four units — no, five, there's one on the back roof," the answer is five, and the fact they nearly missed it means the back roof deserves a note.
+
+If audio is unclear on a number, do not guess it. Flag it: "couldn't make out the tonnage at 0:47 — confirm before this goes out."
+
+---
+
+## Photos
+
+Photos are excellent for some things and worthless for others. Being honest about which is what keeps the owner out of trouble.
+
+**Photos can establish:** equipment make and model from a nameplate, visible condition and age, access constraints, obvious obstructions, approximate layout, what is already installed.
+
+**Photos cannot establish:** dimensions without a reference object, what is behind or above anything, condition of concealed components, code compliance, or capacity.
+
+Never derive a quantity from a photo unless something of known size is in frame. Estimated square footage from a photo is the single most common way a job goes underwater.
+
+State what each photo contributed and what it left open:
+
+```
+Photo 3 shows a Carrier 48TC rooftop unit, nameplate legible, visible rust at
+the base pan. Age not determinable from the plate. Roof access appears to be
+ladder-only — confirm, because a crane changes the number materially.
+```
+
+---
+
+## Drawings and plan sheets
+
+Read the title block first: revision, date, scale, and whether it is issued for construction or preliminary. A quote against a superseded revision is a quote against the wrong job.
+
+Take quantities from schedules and legends, not by measuring the drawing. If a schedule is absent and quantities must be counted, say so and state the count as an assumption.
+
+Note anything marked "by others" or "NIC" — that is scope boundary and it belongs in the not-included section verbatim.
+
+---
+
+## RFPs, RFQs, and solicitations
+
+These are compliance documents before they are pricing documents. A perfect price on a non-compliant response loses.
+
+Extract in this order:
+
+1. **Submission mechanics** — deadline, format, page limits, delivery method. Miss any of these and nothing else matters.
+2. **Mandatory qualifications** — licenses, bonding, insurance limits, certifications, past-performance minimums
+3. **The actual scope of work**
+4. **Evaluation criteria and their weights** — this tells you what the response should emphasize
+5. **Terms that carry cost** — liquidated damages, retainage, payment timing, warranty length, prevailing wage
+
+**Run a go/no-go before writing anything.** If the owner cannot meet a mandatory qualification, say so immediately. Writing a full response to an RFP they are disqualified from is a wasted evening, and this segment does not have spare evenings.
+
+```
+Go/no-go: This requires a USD 2M umbrella policy and you carry USD 1M. That's
+disqualifying unless you can bind additional coverage before the 8th.
+Worth checking before I write the rest?
+```
+
+---
+
+## Scrappy notes
+
+Sometimes it is four lines typed on a phone. That is enough to start, and it is better than the owner writing the proposal from scratch.
+
+Extract what is there, then list what is missing as direct questions — the smallest set that would let the price be real:
+
+```
+Enough here to draft the shape of it. Three things I need before the number
+means anything:
+  - Square footage of the space
+  - Is the existing ductwork staying?
+  - Any deadline you know about?
+```
+
+Three questions, not a form. The owner is answering this on a phone.
+
+---
+
+## Handling the gaps
+
+Every gap resolves one of two ways, and never a third:
+
+**Ask,** when the answer materially changes the price and the owner can get it quickly.
+
+**Assume, in writing,** when the job needs to move. The assumption goes in the proposal itself, in the customer-visible text:
+
+```
+This quote assumes roof access by existing ladder. If a crane or lift is
+required, add USD 1,800.
+```
+
+That sentence has saved more margin than any pricing refinement. It converts a dispute into a pre-agreed line item.
+
+**Never guess silently.** A number with an invisible assumption behind it is the mechanism by which a profitable job becomes a loss.

package/content/small-business/skills/small-business-proposal-builder/reference/gotchas.md

@@ -0,0 +1,184 @@
+# Gotchas
+
+Failure modes that lose money or lose the job. Proposals are binding documents — a mistake here has a dollar value attached.
+
+---
+
+## Gotcha: a quantity estimated from a photo
+
+**Why it matters:** This is the classic way a job goes underwater. A photo without a reference object cannot establish dimensions, and a square-footage guess that is 30% low turns a profitable job into a loss the owner cannot renegotiate.
+
+### Bad
+
+```
+Approximately 4,200 sq ft based on the photos.
+```
+
+### Good
+
+```
+Square footage not determinable from the photos — nothing in frame for scale.
+Two options: give me the number, or I price it per-unit and add a line that
+adjusts on field verification.
+```
+
+Photos establish make, model, condition, and access. They do not establish size.
+
+---
+
+## Gotcha: no "not included" section
+
+**Why it matters:** Scope disputes are the single largest source of lost margin in service businesses, and every one of them starts with something nobody wrote down.
+
+### Bad
+
+Scope section only. Customer assumes ductwork is included. It wasn't.
+
+### Good
+
+An explicit list of what a reasonable customer might assume is covered and isn't. It costs three lines and prevents the argument entirely.
+
+---
+
+## Gotcha: a silent assumption
+
+**Why it matters:** An assumption the owner knows about but the customer never saw is not protection. It becomes the owner's problem the moment it turns out wrong.
+
+### Bad
+
+Price the job assuming ladder access. Mention it to the owner. Leave it out of the document.
+
+### Good
+
+```
+This price assumes roof access by the existing ladder. If a crane or lift is
+required, add USD 1,800.
+```
+
+In the customer-visible text, with the consequence named. That converts a dispute into a pre-agreed change order.
+
+---
+
+## Gotcha: an invented rate
+
+**Why it matters:** Labor rate is the owner's core economics. A plausible-looking number they don't catch either loses them the job or loses them money on it.
+
+### Bad
+
+```
+Line 4 — Controls integration: USD 4,200
+```
+
+Derived from nothing.
+
+### Good
+
+```
+Line 4 — Controls integration: $______
+
+No comparable in your history, nothing in the rate card. Everything else is
+priced. Give me a number and it's ready.
+```
+
+A blank is honest and takes the owner five seconds. A fabricated number takes ten minutes to notice and might not get noticed.
+
+---
+
+## Gotcha: redesigning their template
+
+**Why it matters:** A proposal that doesn't look like their other proposals gets rebuilt by hand, which is the exact work this skill exists to remove. Familiar beats better.
+
+### Bad
+
+Produce a cleaner, more modern layout than the owner's own.
+
+### Good
+
+Match their template exactly, including the parts that could be improved. Offer improvements separately, after the proposal is out the door.
+
+---
+
+## Gotcha: writing an RFP response the owner is disqualified from
+
+**Why it matters:** A full RFP response is an evening of work. If a mandatory qualification can't be met, that evening is gone for nothing, and this segment has no spare evenings.
+
+### Bad
+
+Write the whole response, then mention the insurance requirement at the end.
+
+### Good
+
+Go/no-go first, before drafting anything:
+
+```
+Go/no-go: requires a USD 2M umbrella, you carry USD 1M. Disqualifying unless you
+can bind more before the 8th. Worth checking before I write the rest?
+```
+
+---
+
+## Gotcha: burying the risk in the customer document
+
+**Why it matters:** The owner needs the honest read; the customer needs the proposal. Mixing them either alarms the customer or hides the risk from the owner.
+
+### Bad
+
+Soften the risk into the proposal's assumptions section and say nothing directly.
+
+### Good
+
+Two separate things. The proposal contains assumptions in neutral, customer-appropriate language. The chat message to the owner says what actually worries you, bluntly.
+
+---
+
+## Gotcha: sending without explicit approval
+
+**Why it matters:** A priced proposal commits money, calendar, and reputation, and it cannot be recalled once the customer has read it.
+
+### Bad
+
+Route to DocuSign because the owner said the proposal looked good.
+
+### Good
+
+State what will happen — recipient, total, routing, what fires on acceptance — and wait for a yes on that specific action.
+
+---
+
+## Gotcha: not recording the outcome
+
+**Why it matters:** Won proposals are tomorrow's comparables. Lost ones are more valuable still, and nothing else in the plugin captures them.
+
+### Bad
+
+Send it and move on.
+
+### Good
+
+Record won, lost, or no response, with the final price and the reason when it's known:
+
+```
+Ridgeline — lost. USD 18,650. Dana said a competitor came in at USD 16,000.
+Our per-unit was USD 3,550; theirs implies about USD 3,050.
+```
+
+That single line makes every future quote in this category sharper, and the owner would never have written it down themselves.
+
+---
+
+## Gotcha: a deposit weaker than their standard
+
+**Why it matters:** Deposit terms are cash flow. A quiet drop from 50% to 25% on a material-heavy job can leave the owner financing the customer's equipment.
+
+### Bad
+
+Use a reasonable-sounding deposit without checking what they normally do.
+
+### Good
+
+Pull terms from past proposals, and flag any softening:
+
+```
+Your usual deposit is 50%. I put 40% here since it's a repeat-adjacent
+customer. Change it if you'd rather not.
+```

package/content/small-business/skills/small-business-proposal-builder/reference/output_template.md

@@ -0,0 +1,128 @@
+# Output Template
+
+The owner checks two things before sending: the price and the scope. Structure the review around that, then get out of the way.
+
+---
+
+## Structure
+
+```
+## Proposal — <customer>, <job in four words>
+
+**<total>** · <one line on how it was priced>
+
+Based on: <the comparables used, with dates and amounts>
+
+### Open assumptions
+
+- <assumption> — <what happens if it's wrong, in dollars>
+
+### Worth knowing before you send
+
+- <risk, in plain terms>
+
+<DOCX and PDF attached.>
+
+<Send question.>
+```
+
+Everything above the attachment is for the owner alone. The customer never sees the risk section.
+
+---
+
+## Worked example
+
+```
+## Proposal — Ridgeline Property Group, 5 rooftop units
+
+**USD 18,650** · Priced from your Fairmount job, adjusted for the extra unit
+and the lower-roof access.
+
+Based on: Fairmount Commercial, Mar 2026 — 4 units, same scope, USD 14,200
+          (USD 3,550/unit). Corwin & Bay, Nov 2025 — 6 units, USD 21,300
+          (USD 3,550/unit). Your per-unit number has been steady.
+
+### Open assumptions
+
+- Roof access by existing ladder. If a crane is needed, add USD 1,800.
+  This one is stated in the proposal, so it's a change order rather than
+  an argument.
+- Existing electrical is adequate. Quoted separately if inspection says no.
+
+### Worth knowing before you send
+
+- The lower-roof unit is the risk on this job. Photo 3 shows ladder access
+  only and I couldn't see the parapet height. If it needs a lift, the USD 900
+  allowance won't cover it.
+- Dana mentioned "we paid around 8 last time" on the call. That was for two
+  units, so USD 18,650 for five is consistent — but it's worth saying that out
+  loud in your cover note, because the headline number is more than double
+  what she remembers.
+- Your usual deposit is 50%. I put 40% here because it's a repeat-adjacent
+  customer. Change it if you'd rather not.
+
+Proposal-Ridgeline-2026-07-27.docx and .pdf attached.
+
+Send to Dana for signature via DocuSign, or do you want to change anything first?
+```
+
+The second risk bullet is the kind of thing that wins jobs. It came from the transcript, not from the pricing, and no template would have surfaced it.
+
+---
+
+## When a price line is open
+
+Show the proposal as complete except for the gap, and make the ask trivial:
+
+```
+## Proposal — Corwin & Bay, controls upgrade
+
+**USD 12,400 + controls integration** · Everything priced except one line.
+
+Line 4 — Controls integration: $______
+
+No comparable in your history and nothing in the rate card. Give me a number
+and this is ready to go. Everything else is built.
+```
+
+---
+
+## For an RFP response
+
+Compliance leads, because a perfect price on a non-compliant submission loses:
+
+```
+## RFP response — Marion County, HVAC maintenance, RFP 26-114
+
+**USD 84,000/yr** · 3-year term, priced from your commercial service contracts.
+
+### Compliance check
+
+✓ USD 2M umbrella — bound Jul 12
+✓ CCB license current
+✓ 3 references, all commercial, all over 2 years
+⚠ Prevailing wage applies. I priced at the current rate sheet, which is
+  about 22% over your standard labor. Confirm that's right.
+
+Due Aug 8, 2 pm, submitted via county portal. Page limit 15; we're at 12.
+
+### Worth knowing before you send
+
+- Liquidated damages are USD 500/day past the response window on emergency
+  calls. That's aggressive for a maintenance contract and it's the main
+  reason to walk if you're not confident on staffing.
+```
+
+---
+
+## Rules
+
+**Lead with the number.** It is what the owner opens the message to see.
+
+**Always show the comparables.** It is the difference between a price the owner can approve in ten seconds and one they rebuild from scratch.
+
+**Keep the risk section honest and separate.** It never appears in the customer document. Softening it to be encouraging removes the only reason it exists.
+
+**One send question at the end.** Not a checklist of options — a single yes-or-change.
+
+**Never send without an explicit yes.** A priced document commits the owner's money, their calendar, and their reputation.

package/content/small-business/skills/small-business-proposal-builder/reference/pricing_method.md

@@ -0,0 +1,125 @@
+# Pricing Method
+
+Price from what this owner has actually charged. Not from a general estimate, not from an industry average, and never from a plausible-sounding number.
+
+The owner can sanity-check a price in ten seconds if they can see what it was based on. They cannot check a number that appeared from nowhere, so they rebuild the whole thing by hand — which is the work this skill was supposed to remove.
+
+---
+
+## The method
+
+**1. Find comparable jobs.**
+
+Pull past invoices and proposals for similar work:
+
+- The connected ledger's invoices with line detail (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) — what was actually billed, which is what makes them comparable
+- A payments connector's charge history by customer (PayPal, Square, or Stripe) when no ledger is connected — totals only, so the line arithmetic has to come from the owner
+- Past proposals in Drive or M365
+- An uploaded price list or rate card
+- Anything the owner pastes in
+
+A good comparable matches on type of work, rough scale, and customer type. Two or three is plenty. One is thin but usable if it is close.
+
+**2. Build from the comparable, adjust for difference.**
+
+State the arithmetic:
+
+```
+Comparable: Fairmount Commercial, Mar 2026 — 4 rooftop units, same scope.
+            USD 14,200 total, USD 3,550 per unit.
+
+This job:   5 units, one on a lower roof with harder access.
+            5 x USD 3,550 = USD 17,750
+            + USD 900 access allowance for the lower roof unit
+            = USD 18,650
+```
+
+The owner reads that and either agrees or adjusts one number. That is the whole point.
+
+**3. Check it against the rate card, if one exists.**
+
+If the derived price is more than about 15% away from the rate card, say so and explain which you used and why. A silent discrepancy is how a shop ends up with two different prices in the market.
+
+---
+
+## When there is no comparable
+
+Do not invent one. Leave a placeholder, be specific about what is needed, and build the rest of the proposal around it:
+
+```
+Line 3 — Controls integration:  $______
+
+I have no comparable for controls work in your history and no rate card entry.
+Everything else is priced and ready. Give me a number for this line and the
+proposal is done.
+```
+
+That is a five-second ask. A fabricated USD 4,200 is a number the owner has to notice, distrust, and replace — and might not catch.
+
+---
+
+## What must never be invented
+
+| Never invent | Why |
+|---|---|
+| A labor rate | It is the owner's core economics |
+| A material cost | It moves constantly and varies by supplier |
+| A lead time | It is a promise to the customer |
+| A quantity from a photo | Estimated square footage is the classic way a job goes underwater |
+| A subcontractor's price | Not the owner's number to give |
+| A discount | Discounting is always the owner's call |
+
+---
+
+## Structuring the price
+
+**Break it into lines the customer understands.** A single number invites a single objection. Four lines invite a conversation about scope, which is a better conversation.
+
+But do not itemize down to fasteners. Lines should map to things the customer recognizes as decisions:
+
+```
+Good:
+  Equipment — 5 rooftop units, installed          USD 14,800
+  Electrical and controls                          USD 2,100
+  Roof access allowance, lower unit                  USD 900
+  Permit and inspection                              USD 850
+                                                  --------
+  Total                                            USD 18,650
+
+Bad:
+  Materials                                       USD 11,240
+  Labor                                            USD 7,410
+```
+
+The good version lets a customer cut the access allowance or supply their own permit. The bad version lets them only say "too expensive."
+
+---
+
+## Options, when they help
+
+Two or three tiers work well when the customer's budget is unclear. More than three is paralysis.
+
+Anchor with the recommended option, and say which it is and why in one line. An unlabeled menu makes the customer do the owner's job.
+
+Never present an option the owner would not actually want to do. A cheap tier that produces a bad outcome damages them when the customer picks it.
+
+---
+
+## Terms
+
+Pull the owner's standard terms from past proposals rather than inventing them. If none exist, use conservative defaults and flag them for confirmation:
+
+- Deposit: 30% to 50% for material-heavy work, less for pure labor
+- Payment: net 15 or net 30, matched to what their invoices already say
+- Validity: 30 days, or shorter when material prices are moving
+- Change orders: written approval before work proceeds
+
+**Flag terms weaker than their usual.** If their standard is 50% deposit and this proposal says 25%, that is worth saying out loud before it goes to the customer.
+
+---
+
+## Recording the outcome
+
+After a proposal is sent, record what happened — won, lost, or no response — with the final price and the reason if known.
+
+Won proposals become tomorrow's comparables. Lost ones are just as valuable: knowing that USD 18,650 lost the Ridgeline job to a competitor at USD 16,000 is the only way the next quote gets sharper. Nothing else in the plugin captures that, and owners almost never track it themselves.

package/content/small-business/skills/small-business-proposal-builder/reference/proposal_structure.md

@@ -0,0 +1,120 @@
+# Proposal Structure
+
+Use the owner's own template when one exists. This structure is the fallback, and it is also what to offer to save as their template if they have never had one.
+
+---
+
+## Sections, in order
+
+**1. Header**
+
+Owner's business name and contact, customer name and contact, date, proposal number, and a validity date. The validity date protects the owner when material prices move.
+
+**2. What you asked for**
+
+Two or three sentences restating the customer's need in their own words, pulled from the discovery. This is not filler — customers scan for whether the vendor actually understood the job, and most proposals fail that test in the first paragraph.
+
+**3. What we'll do**
+
+The scope, in specifics. Quantities, equipment, locations, and sequence where it matters.
+
+Write it so a stranger could tell whether the work was completed. "Upgrade the HVAC system" is not scope. "Replace five rooftop units with Carrier 48TC, reconnect existing ductwork and electrical, haul away old units" is.
+
+**4. What's not included**
+
+The most valuable section in the document. Scope disputes are where service businesses lose money, and they begin with what nobody wrote down.
+
+Include anything a reasonable customer might assume is covered:
+
+```
+Not included:
+  - Ductwork replacement or modification beyond reconnection
+  - Electrical service upgrades, if required by inspection
+  - Roof repair or patching beyond the curb penetrations
+  - Crane or lift, if roof access proves inadequate (see assumptions)
+  - After-hours or weekend labor
+```
+
+Every line is a conversation that happens now instead of an argument later.
+
+**5. Assumptions**
+
+The conditions the price depends on, in customer-visible language, each with what happens if it turns out otherwise:
+
+```
+This price assumes:
+  - Roof access by the existing ladder. If a crane or lift is required, add USD 1,800.
+  - Existing electrical service is adequate. If an upgrade is needed, quoted separately.
+  - Work performed during normal business hours.
+```
+
+Naming the consequence converts a dispute into a pre-agreed change order.
+
+**6. Investment**
+
+The price, broken into lines the customer recognizes as decisions. Options presented as clearly labeled tiers if used, with the recommended one named.
+
+**7. Timeline**
+
+Start window, duration, and what it depends on. Say what would move it — permit approval, equipment lead time, customer access. A timeline with no dependencies listed is a promise the owner cannot keep.
+
+**8. Terms**
+
+Deposit, payment schedule, change-order process, warranty, validity window.
+
+**9. Next step**
+
+One sentence. Not "we look forward to hearing from you" — an actual instruction:
+
+```
+Sign below and I'll order the units. Lead time is 3 weeks from deposit.
+```
+
+**10. Signature block**
+
+Both parties, with dates. When DocuSign routes it, the fields go here.
+
+---
+
+## Length
+
+Most SMB proposals should run two to four pages.
+
+An RFP response goes as long as the RFP requires — compliance beats brevity there, and page limits are usually mandated anyway.
+
+A repeat customer for routine work can take one page. Do not make a customer who has bought this six times read a full proposal.
+
+---
+
+## Tone
+
+Match [the shared voice profile](../../../shared/voice-profile.md). A proposal that reads nothing like the owner's emails is jarring, and the customer has usually already exchanged mail with them.
+
+**If that file has no profile yet**, follow its "When there is no sample" instruction — ask for three emails the owner was happy with. If they decline, write plain and neutral and say the proposal is un-voiced. Never invent a personality.
+
+Plain language throughout. This audience sells to people reading on a phone between jobs.
+
+Avoid the standard proposal padding: no mission statement, no "why choose us" section, no stock photos of handshakes. Owners in this segment win on being clear and being responsive, and a padded document undercuts both.
+
+---
+
+## Formatting
+
+- DOCX and PDF, both, every time. The customer wants the PDF; the owner sometimes needs to edit.
+- Owner's logo and colors when available from the template or brand assets
+- Price table right-aligned on numbers, currency formatted as currency
+- Page numbers and the proposal number in the footer, so pages don't get separated
+- Signature block on its own page if the document runs past two pages
+
+---
+
+## Offering to save it as a template
+
+If the owner had no template and the proposal comes out well, offer once:
+
+```
+Want me to save this layout as your standard proposal template? Next one would
+start from it instead of from scratch.
+```
+
+If yes, store it so later runs match. That is the difference between a skill that saves an evening once and one that saves an evening every week.