Expand init to capture positioning, conversion, and proof context

[abdulwahabone]

Motivation

Init should pull more strategic context out of the repo before writing PRODUCT.md. Downstream commands (craft, shape, critique, clarify) need positioning, conversion intent, and proof to work from, not just audience and personality guessed from a crawl.

---

Brand register: interview tone (3 examples)

Questions stop quoting init.md vocabulary and read more like a magazine editor profiling the brand.

Topic	Before (main)	After (this branch)
Register	"Register: does brand match your intent? … brand register (marketing/editorial surfaces are the primary design context)"	"From the codebase, this reads as a marketing site: editorial pages, a hero, service lanes, and booking CTAs, not an app or dashboard. Does that match your intent?"
Audience	"Users & purpose: who is this really for?" (three sub-questions in one block)	"Who is the primary person you are designing for?" (one question; job and success follow separately)
References	"References and anti-references: be specific" (lumped together, asks for names + anti-patterns in one breath)	"Name one or two sites, studios, or brands whose feel is close, and say what specifically you'd borrow" (references first; anti-references get their own question next)

---

PRODUCT.md: what changed

Examples from harness runs on two fixture projects: a Tokyo flower atelier marketing site (brand register) and a small-team HR ops app (product register).

Brand register (flower atelier marketing site)

Before (main): label-heavy Users; conversion intent folded into Product Purpose; no Positioning or Conversion & proof sections.

## Users

**Primary:** Wedding couples planning high-end floral commissions…
**Secondary:** Event planners who refer or co-plan with couples…
**Context:** Visitors arrive with intent, not to browse casually…
**Core job on landing:** Decide whether Hanazono can deliver their wedding vision…

## Product Purpose

…**Success (6–12 months):** A steady flow of qualified wedding inquiries…
**Primary conversion:** Book a consultation / start a wedding floral quote…

## Brand Personality

**Three words:** Restrained · Seasonal · Composed
**Voice:** Quiet luxury with seasonal warmth…
**Reference feel (what to borrow, specifically):**
- **Kinfolk:** generous whitespace and slow horizontal rhythm…
- **Cereal magazine:** muted, film-like photography treatment…

After (this branch): new Positioning and Conversion & proof sections; Users and personality in prose; proof paths wired in.

## Users

Couples planning their own wedding are the primary audience… Wedding planners who refer
or co-plan with couples are secondary. When someone lands on the site, the core job…
is inquire about a corporate gifting program.

## Positioning

Seasonal florals composed with restraint, ikebana-influenced, not trend-chasing.

## Conversion & proof

Primary CTA is to inquire about corporate gifting. Secondary CTA is to learn about
the studio at `/about`.

The line a visitor should remember after ten seconds: "Seasonal florals, composed with restraint."

Belief ladder: this isn't commodity delivery, then seasonal work is the point, then Tokyo
atelier credibility, then consultation is the natural next step.

Proof on hand:
- `.impeccable/assets/proof/testimonial-tokyo-grand-hotel.txt`
- `.impeccable/assets/proof/press-clipping.txt`
- `.impeccable/assets/proof/client-logo-verdant-events.png`

## Brand Personality

Editorial · Ikebana-influenced · Tokyo-atelier. Reference feel: editorial print (Kinfolk, Cereal):
generous whitespace, slow scroll, literary captions. Emotional goal: calm and confident,
not loud or promotional.

Product register (HR ops app for small teams)

Before (main): solid ops brief, but no positioning line; users/workflow still read as labeled blocks.

## Users

**Primary:** People managers and HR admins at companies with 15–80 employees. They open
the app 3–5 times a week, often between meetings…

**Job to be done:** Know what needs their attention right now: pending PTO approvals,
onboarding gaps, headcount changes…

**Primary workflow:** From the dashboard, see pending items and clear the queue
(approve/decline PTO, spot onboarding gaps) in under a minute without leaving the page.

## Product Purpose

Replace the spreadsheet-and-Slack patchwork for day-to-day HR operations…

Success after a few weeks: Managers trust the dashboard as their morning check-in and
rarely fall back to spreadsheets for people ops.

## Brand Personality

**Calm, decisive, trustworthy.** Fast to scan, never shouty…

After (this branch): adds positioning; same facts, cleaner prose. No conversion block (correct for product register).

## Users

**Primary:** People managers at companies with 15–80 employees, usually a team lead
or department head who handles PTO approvals, onboarding checklists, and headcount
visibility a few times per week…

**Job to be done:** See whether anyone on their team is blocked (pending PTO, stalled
onboarding) and clear or escalate it in under two minutes.

**Primary workflow:** From the dashboard, spot the one urgent metric or overdue item
and jump straight to the action…

## Product Purpose

Replace the spreadsheet + email thread for people ops. Success means managers stop
maintaining a parallel HR tracker and trust the app as the single place to answer
"who's out, who's starting, what's overdue."

## Positioning

HR ops for small teams that outgrew spreadsheets but don't need an enterprise HRIS:
fast visibility without implementation theater.

## Brand Personality

**Direct, calm, trustworthy:** no cheerleading, no enterprise gravitas.

Product interviews stay plain and ops-focused. No magazine-editor voice, no conversion/proof round.

---

Other init.md fixes (from harness)

• One topic per question; compound MCQ options forbidden
• Split register settled before brand-only questions
• Confirmed answers only at write time (no crawl/option-text padding)
• PRODUCT.md prose: bold sparingly, not label lead-ins on every line

---

Note

Low Risk
Documentation-only change to the init skill reference; no runtime code, auth, or data paths affected.

Overview
Init guidance now pulls richer strategic context into PRODUCT.md so downstream commands (craft, shape, critique, clarify) can rely on explicit positioning and conversion intent, not just crawl-inferred audience and tone.

The Step 3 interview is tightened: ask only where the repo lacks strong evidence; one topic per question (no compound MCQs); settle register before brand-only rounds; use plain, user-facing language (magazine-editor tone for marketing sites). New question areas cover positioning (one-line strategic claim), expanded users & purpose (confirm README hypotheses, primary/secondary audiences, surface vs product users), and conversion & proof for the brand register (CTAs, memorable line, belief ladder, proof assets under .impeccable/assets/proof/).

Step 4’s PRODUCT.md template adds ## Positioning and ## Conversion & proof (omitted entirely for product register), tightens Users prose, and requires writing only confirmed answers—no padding from crawl or option text—with sparing bold instead of label-heavy blocks.

^{Reviewed by Cursor Bugbot for commit c7e44d8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR expands /impeccable init so it captures more strategic context before writing PRODUCT.md. The main changes are:

• Adds positioning as a required interview and PRODUCT.md field.
• Adds brand-only conversion and proof prompts for CTAs, remembered line, belief ladder, and proof assets.
• Tightens interview guidance around one-topic questions, confirmed answers, and user-friendly phrasing.
• Updates the PRODUCT.md template guidance to use prose with sparse bold text.

Confidence Score: 4/5

Low-risk documentation-only change to the init skill reference.

No new unaddressed blocking issues were found in the changed file. The change is limited to skill/reference/init.md and does not touch runtime code, auth, data paths, or generated provider output.

skill/reference/init.md only for the already-discussed brand-only template heading ambiguity.

T-Rex Logs

What T-Rex did

• Attempted the highest-value PR-scoped behavior test, but the command exited with code 1 due to zero tool calls in all LLM-backed scenarios.
• Saved a fallback validation harness named init-reference-assertions.mjs to enable contract validation.
• Executed the fallback harness and observed a successful run indicating all assertions passed.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
skill/reference/init.md	Expands init guidance to collect confirmed positioning plus brand-only conversion/proof context before writing PRODUCT.md; the known template ambiguity around the brand-only section was already raised in an earlier thread.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Init as /impeccable init
participant Repo as Codebase crawl
participant User as User interview
participant Product as PRODUCT.md

Init->>Repo: Scan docs, config, components, assets
Repo-->>Init: Register hypothesis and explicit evidence
Init->>User: Confirm register first
User-->>Init: brand or product
Init->>User: Ask focused strategic questions
alt brand register
    Init->>User: Ask conversion and proof questions
    User-->>Init: CTAs, remembered line, belief ladder, proof assets
else product register
    Init->>User: Ask workflow and purpose questions
    User-->>Init: Users, job, success, positioning
end
Init->>Product: Write confirmed prose fields

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Init as /impeccable init
participant Repo as Codebase crawl
participant User as User interview
participant Product as PRODUCT.md

Init->>Repo: Scan docs, config, components, assets
Repo-->>Init: Register hypothesis and explicit evidence
Init->>User: Confirm register first
User-->>Init: brand or product
Init->>User: Ask focused strategic questions
alt brand register
    Init->>User: Ask conversion and proof questions
    User-->>Init: CTAs, remembered line, belief ladder, proof assets
else product register
    Init->>User: Ask workflow and purpose questions
    User-->>Init: Users, job, success, positioning
end
Init->>Product: Write confirmed prose fields

Loading

_{Reviews (3): Last reviewed commit: "Keep belief-sequence question out of ski..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 150a1ea. Configure here.}