How to use
Paste everything between the two --- markers below into your chat, replacing <TOPIC> with the thing you want researched. Attach any raw-dump material inline. Hit send.
If the session has repo access, also say: “read https://github.com/361-coders-nz/oxflow-hub/blob/main/research/2026-04-17-database-analysis.md as an exemplar.” That pulls an actual reference note as an anchor.
You’re writing a research note for the 361 Software team. The team is building oxFlow — a construction cost management platform for Oxcon, a New Zealand civil construction firm. The note must match the house quality level established by the four research notes committed to github.com/361-coders-nz/oxflow-hub on 2026-04-17 and 2026-04-20 (database analysis, shared project memory, agentic coding + PR review, Multica + Managed Agents).
Topic
<TOPIC> — replace this line with the actual research question, one or two sentences. Paste any raw-dump material (links, screenshots, quotes, half-formed thoughts) underneath.
Audience + voice
- Reader is a 3–5 dev NZ team. Technical, opinionated, time-boxed. Phase 1 ships June 27 2026.
- Write in sentence case. UPPERCASE is reserved for labels (eyebrow tags, table headers).
- Be direct. “Use X.” not “Teams may wish to consider X.” The research earns authority by citing; don’t pad it with qualifiers.
- No decorative words — no “seamless”, “sleek”, “powerful”, “cutting-edge”. The content has to do the work.
- NZ / Oxcon context where relevant: ap-southeast-2 Sydney pricing, NZ Privacy Act for managed services, Workbench (NZ construction ERP by Derivative) as the legacy system being replaced.
Existing stack (context — don’t re-pick these unless the research explicitly justifies it)
- Data tier: Neon serverless Postgres (ap-southeast-2) + AWS S3. Locked via the DB analysis note.
- Env / CI: GitHub + Render + Neon, GitHub Flow with staging gate, Neon branch-per-PR. Locked via Ibrahim’s DevOps note.
- App stack: NestJS + React + TypeScript + Drizzle ORM.
- Team workflow: Claude Code locally +
anthropics/claude-code-actionin CI + CodeRabbit for first-pass PR review. BMAD method used partially for planning.
If the topic overlaps with any of these, cross-reference rather than contradict.
Required output — one markdown document with ALL of these sections
# Research — <topic>
**Date:** YYYY-MM-DD
**Author:** Real Name (@handle) <!-- whoever ran the session -->
**Status:** draft
**Prompted by:** <link back to the daily log / meeting / dump that triggered this>
## Question
One or two paragraphs framing the specific question this research answers and the constraints.
## TL;DR
80–160 words. Include **a bold recommendation sentence** — the reader should be able to stop here and know what to do. Name the thing, name the alternative, name the revisit trigger.
## Approach
60–120 words. How was this researched? Web search + multiple-agent delegation / interviews / vendor docs / community threads — whatever was actually done. Be honest about depth and limits.
## Findings
H3 subsections per topic area. 1,200–2,800 words total. End each subsection with a crisp conclusion line.
Must include at least one of each, built into the prose naturally:
- **Candidate comparison matrix** — markdown table. Columns appropriate to the topic (e.g. vendor × pricing × compliance × fit). Traffic-light cells where semantic (green = recommended / locked, amber = viable / later, red = rejected / wrong shape).
- **Ranked shortlist** — numbered 1–N list with the top entry clearly flagged.
- **Inline-cited URLs** — every concrete claim has a source next to it, not just at the bottom.
## Recommendation for 361
200–500 words. Opinionated. Name the thing, say why it matches the existing stack, say what it costs (in USD unless NZD is specifically warranted), say how it gets wired in (day-by-day or week-by-week rollout).
## Alternatives considered
150–400 words. Bulleted list. For each rejected alternative: one line on what it is + one line on why it lost + one line on the revisit trigger.
## Sources
**At least 20 cited URLs.** Group by theme (e.g. Vendor docs / Community reviews / Benchmarks / Related research). Every URL should have been cited inline above — this list is the index, not a brain-dump.
## See also
- [Sibling research notes in the repo that this one relates to]
- [ADRs / decisions / specs this informs]
- [`BRANDING.md`](../BRANDING.md) — if producing an HTML companion
## Linked from
- [Back-pointer to the daily log / meeting / dump that triggered this]Total markdown: 2,000–4,000 words.
HTML companion (produce if asked for “MD + HTML”)
Ship a standalone .html at the same slug. Requirements:
- Use only the colour tokens and named components from
https://github.com/361-coders-nz/oxflow-hub/blob/main/BRANDING.md. No Tailwind, no Bootstrap, no external UI framework. Paste the:rootblock verbatim. - Include the
.geo-bgfixed grid background — it’s the single strongest brand cue. - Use these named components as the vocabulary:
.eyebrow,.tldr(green callout),.pipeline,.layer-stack,.mini-table,.card-row,.bullets,.sources. - Include at least one inline SVG diagram — system shape, flow, decision path, or relationship map. No external image deps. Hand-drawn SVG with the ink + accent palette.
- Fade-up entrance animations with staggered
.animate-up .delay-Non each section. - Mobile-responsive via the single
@media (max-width: 760px)block used in the reference HTMLs. - Footer: link back to the markdown companion, sibling notes, and
BRANDING.md.
Research rigour — non-negotiable
- Cite at least 20 URLs. Pricing pages, docs, blog posts, GitHub repos, benchmark writeups, community threads. Inline the citations where claims are made.
- Name the vendor / project / tool. Link the repo. Quote the pricing number. Flag beta / preview / GA status.
- Declare confidence. “Confirmed via
” / “Strongly suggested by ” / “No public info — speculation, based on .” Don’t present speculation as fact. - Price in USD unless NZD is specifically warranted. Prefer ap-southeast-2 Sydney pricing. If a vendor has no Sydney region, call that out — for an NZ-only tenant, that’s a real constraint.
- Cross-check against prior committed research. The four existing notes referenced above are shared context. Don’t contradict them silently.
Exemplars (read at least one before starting)
- Database analysis — 2,800+ words, comparison matrix, per-candidate deep-dive, Workbench migration section, explicit Neon + S3 recommendation, 35+ sources.
- Shared project memory — landscape survey with ranked shortlist and week-by-week rollout.
- Agentic coding + PR review — product-landscape comparison with numbers and a one-week wire-in plan.
- Multica + Claude Managed Agents — includes end-to-end system diagram and USD cost envelope.
Delivery
Write the markdown as a single self-contained document. If the HTML companion is requested, write it as a second artefact. Both can be committed directly to main under research/YYYY-MM-DD-<slug>.md + .html — no PR needed for research-only output (see raw-dumps/README.md for the guardrails on direct pushes).
Commit message prefix if the deliverable is auto-generated: auto-research:.