DEV Community: Software Sausage

CRM Trial Checklist: Test Your Workflow Before You Buy

Constantine Macris — Sat, 19 Sep 2026 22:07:42 +0000

Disclosure: Software Sausage is our product. This is a free worksheet and a proposed workflow, not a measured customer result or sponsored ranking.

CRM Trial Checklist: Test Your Workflow Before You Buy

Before comparing CRM feature lists, make each candidate complete the same small job: record an inquiry, assign it, follow up, hand it to delivery, and get the useful data back out. Keep the evidence—not just a star rating.

Download the free CRM trial scorecard. No signup. All sample people and businesses are fictional. The CSV has no macros, formulas, or automatic reminders.

Start with a small, safe trial

Download the scorecard and the linked five-client spreadsheet. These are fictional records, not prospects to contact. Use a separate test workspace with no real client data. Disable automated outreach; do not connect your production inbox, billing, or live workflows.

Use the same records, role assumptions, and tests for each candidate. Make a separate scorecard copy per tool. Record the product, plan, trial date, and tester alongside your evidence. Map fields deliberately: one generic CSV is not a universal one-click importer.

Where supported, create five contacts and five opportunities from the five sample rows, preserving their stable IDs as reference fields. If the tool needs separate company records, create and count those separately. Add a harmless note and dummy attachment to one opportunity.

Run these ten checks

Import and mapping. Five intended contacts and five opportunities exist; IDs, stages, dates and relationships are correct. Record rejected rows rather than silently dropping them.
Owner and next action. Each open opportunity has an accountable owner, a useful next step and a due date. Count incomplete records.
Due-date review. For the sample date 2026-09-19, find the two due open actions. Exclude Won and Closed. Use a date filter rather than assuming today's live dashboard matches the fixture.
Interaction history. Add a harmless note and activity. A second authorized teammate can find the context without being shown which screen to open.
Sales-to-delivery handoff. Move the fictional proposal to Won in your test copy. The delivery owner can locate the agreed scope and next task without copying notes between tools.
Visibility and permissions. With two test accounts, verify the access boundary your business actually needs. If your trial cannot exercise the intended role, mark it UNTESTED.
Duplicates and corrections. Re-import or update one test record using the documented method. Record whether it updates, duplicates, or rejects the row, then return to the five-record baseline.
Report reconciliation. Independently count open opportunities and add their values. The tool's matching report must agree on stage, currency and filters.
Export and reconstruction. Export the records plus available notes and activities. Inspect files outside the CRM and test import into a separate destination or worksheet. Identify anything that cannot be reconstructed.
Plan and operating cost. Identify the plan that supports the tested workflow, any add-ons, the billing term, and who administers it. Record written evidence; a trial feature is not proof it is included in the intended plan.

Do not average away a failure

Every row starts UNTESTED. Change it to PASS only when you complete the scenario and save evidence; use PARTIAL for a documented workaround and FAIL when the requirement is not met. A sales promise remains UNTESTED until checked.

Decide which requirements are mandatory before testing. Our worksheet defaults to mandatory checks for a team scenario; a solo operator may mark shared-role checks optional before starting. A mandatory FAIL blocks the choice; a mandatory PARTIAL or UNTESTED needs resolution or an explicit, owned exception—not an invisible average.

Example only: if the pipeline works but only the administrator can export the required history, that is not a clean PASS for a non-admin export requirement. Record the actual role, limitation, repair work and owner. We have not run this worksheet against vendor trials or published product scores.

An export button is not the same as an exit

HubSpot documents record exports as current property values and associations, with separate routes for contact activities such as notes and calls. Source: HubSpot's record-export documentation, checked 19 September 2026.

Pipedrive documents separate exports for linked activities, notes and files. Its global export also excludes files stored in Google Drive. Source: Pipedrive's export documentation, checked 19 September 2026.

Those are reasons to inspect exported artifacts, not claims that either product is unsuitable. Document automation, reports, roles, integrations and attachments separately; a CSV alone does not show that the working process can be rebuilt.

Sources and limits

Reviewed 19 September 2026. Vendor behavior and plan limits can change; verify them in your own account. The routines and decision rules are our proposed method, not a standard or a product certification.

Use the next step only if you need it

Use the same checklist for managed or self-hosted candidates. For self-hosting, also require an owner for updates, backups and a tested restore. If no candidate passes, simplify the workflow or seek implementation help; do not turn unresolved tests into a recommendation.

Download the five-client fixture and follow-up template. See a sample decision report.

Canonical article: https://softwaresausage.com/blog/crm-trial-checklist

Free Client Follow-Up Spreadsheet for Small Service Businesses

Constantine Macris — Sat, 19 Sep 2026 22:07:41 +0000

Disclosure: Software Sausage is our product. This is a free worksheet and a proposed workflow, not a measured customer result or sponsored ranking.

Free Client Follow-Up Spreadsheet for Small Service Businesses

A contact list tells you who you know. A follow-up list tells you what to do next. If you run a small agency, consultancy, or studio, start with one owner, one next action, and one due date for every open opportunity.

Download the free follow-up spreadsheet. No signup. All sample people and businesses are fictional. The CSV has no macros, formulas, or automatic reminders.

What is in the download?

The CSV opens in Excel and can be imported into Google Sheets. It contains five fictional businesses using reserved .example email addresses. It has no macros, formulas, email sending, or connection to your inbox. No signup is required.

The fields are record ID, company, contact name, email, stage, owner, last contacted, next action, next-action due date, project value in USD, contact preference, and notes. Use one row per opportunity. Keep its ID stable when names or stages change. Rename the currency column if needed; do not sum mixed currencies.

Set it up without making it a project

Download the CSV and import it into a new, private spreadsheet. In Excel, use Data → From Text/CSV if opening it directly changes dates or splits columns incorrectly. Choose comma as the delimiter and preserve record IDs as text.
Freeze the header and enable filters. Keep dates consistent as YYYY-MM-DD, checking that your spreadsheet recognizes due dates as dates before sorting.
Use the examples to learn the routine, then delete them and enter only contacts you are authorized to retain. Replace the example dates with your own; they are not a live task list.
Choose a small set of stages: New, Conversation, Proposal, Won, Closed. Make a dropdown in your spreadsheet if helpful. The CSV itself does not enforce allowed stages.
Restrict sharing to the people doing the work. Do not publish a live client sheet or put confidential proposals, passwords, payment details, or sensitive personal information in notes.

The daily check: who needs a decision today?

Filter out Won and Closed. Find open rows with a missing owner, next action, or due date first. Those are incomplete handoffs, not reminders. Then filter the remaining active rows for next-action dates on or before today.

Using 2026-09-19 as the fictional review date, the sample has three open opportunities and two actions due: Northstar Example Studio and Cedar Example Consulting. Harbor Example Design is due later. This is a worksheet example, not a customer result.

After an appropriate contact, update last contacted and replace the next action and date. If the person declines or asks not to be contacted, mark the record Closed and record that preference. Do not confuse having an email address with permission for a campaign.

Schedule a short calendar block to review the sheet. This file does not send notifications. If nobody will check it, changing its colors will not solve missed follow-ups.

Write the next action so someone else could do it

Weak: Follow up. Better: Ask whether the revised scope answers the client's two questions. Weak: Waiting. Better: Review the agreed decision date; close the opportunity if the client has declined.

For Northstar, the example action is to confirm a discovery-call time. Once the call is booked, replace that with preparing two scope questions and the new due date. A next action should describe the next useful step, not a reason to send another message.

At a weekly review, examine overdue open rows, opportunities with no next step, and proposals with no agreed decision date. A project-value column is an estimate, not revenue or a probability-weighted forecast.

When the spreadsheet is enough—and when to stop

Keep the sheet if the person responsible can maintain it and your team can see the next step without reconstructing the conversation from several inboxes. There is no universal contact-count threshold that makes a CRM necessary.

Run a CRM trial when you need reliable reminders, multiple activity records per opportunity, controlled visibility, a shared interaction history, or a repeatable sales-to-delivery handoff that this sheet cannot provide. Do not migrate simply because a contact list looks less impressive than a dashboard.

This template does not provide per-record access controls, an audit trail, deduplication, email sync, or automation. Do not treat a shared spreadsheet as a substitute for those requirements. Start with the linked trial checklist when one of them becomes necessary.

Sources and limits

Use the next step only if you need it

Use the free sheet first. If it exposes a real software decision, our sample decision report shows what the optional paid analysis adds. You do not need to buy a report to download or use this worksheet.

Test a CRM with the same fictional clients. See a sample decision report.

Canonical article: https://softwaresausage.com/blog/client-follow-up-spreadsheet

You probably do not need 264 AI agents

Constantine Macris — Thu, 10 Sep 2026 03:44:56 +0000

Disclosure: Software Sausage is our product. Agency Agents did not sponsor, review, or endorse this article. AI tools helped draft and edit it; the evidence boundary is stated below.

You probably do not need 264 AI agents. You need bounded roles and a gate

The Agency Agents repository is difficult to ignore: 264 specialized agent definitions, broad coding-harness support, and—when I reviewed it on September 9, 2026—roughly 151,000 GitHub stars.

The tempting conclusion is that a larger virtual team produces better work.

The repository does not establish that. What it does provide is a useful, MIT-licensed role library and a competent installer. The value comes from selecting a few narrow roles and making their outputs pass real checks.

This is a source review at commit 6d29a9b, not a benchmark. I inspected the role files, installer, converter, contribution rules, workflow example, and current GitHub checks. I did not evaluate every integration or the desktop app.

What it gets right

Agent definitions are not one-line personas. They name deliverables, workflows, constraints, and success metrics. The project converts them for Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Qwen Code, Aider, and other harnesses.

More importantly, the installer lets you select one role or division, show a dry run, and target an explicit path. Agency Agents itself warns that OpenCode currently registers only about 119 agents and recommends installing a subset.

The project's contribution guide contains the best design rule: a new agent needs a narrow specialization, distinct behavior, concrete deliverables, measurable success, and real testing. Near-duplicate re-skins are rejected.

That rule should apply to the workflow too. If two roles produce the same artifact, if nobody consumes an output, or if success cannot be checked, remove the role.

What it does not prove

The README's “never sleep” and “always deliver” language is marketing. Prompts still fail, time out, overrun context, and agree on the same plausible mistake.

A role prompt also does not create process isolation. Giving a “reviewer” the same credentials and write access as the implementer makes the label cosmetic.

The repository's seven-agent startup example recommends passing full outputs between roles. Its newer Multi-Agent Systems Architect warns about context growth and recommends summaries and structured state. Use the second rule.

Green installer and manifest checks show that the repository is maintained and internally consistent. They do not show that seven agents outperform one capable agent on correctness, elapsed time, or cost.

Recipe one: one writer, two read-only reviewers

For a software change, three responsibilities are enough:

The Minimal Change Engineer receives one outcome, explicit exclusions, allowed files, and an acceptance command. It can write code but cannot deploy.
The Code Reviewer receives the task, diff, and check log with read-only access. It separates blockers, suggestions, and nits.
The AI-Generated Code Security Auditor receives the same evidence plus the relevant trust boundaries. It uses local, read-only checks and records evidence for each finding.

The implementer gets at most two corrections. Then a person resolves the findings, reruns the repository checks, captures fresh runtime proof, and decides whether to ship.

The free three-agent code-change kit includes the handoff ledger and verifier.

Recipe two: make multi-agent earn its keep

If the question is whether orchestration helps, compare it with one agent:

Freeze a resettable task and choose correctness, cost, latency, intervention, safety, and privacy thresholds before the run.
Run one agent with the model, budget, tools, permissions, and fixture recorded.
Let the architect choose no more than three challenger roles. Define each input, output, permission, fallback, one human gate, and a two-retry cap.
Run the challenger on an identical fresh fixture. Pass agreed artifacts and summaries, not accumulated chat transcripts.
Apply the same deterministic verifier and blind rubric to both results.
Keep orchestration only when it clears the predeclared threshold. Retain failed and stopped runs.

The free multi-agent experiment kit provides the comparison manifest.

The useful default

Start with one agent. Add one role only when it owns a distinct artifact with a consumer and an acceptance check. Keep permissions separate. Cap retries. Leave the human at the irreversible boundary.

Agency Agents makes roles easy to install. The harder—and more valuable—work is proving which ones deserve to stay.

The complete source review and both pullable kits are at Software Sausage. The public Software Sausage MCP endpoint can also find these recipes and return their complete run ledgers inside a compatible agent client.

Zapier vs. Activepieces vs. n8n: count the run, operator, and exit

Constantine Macris — Mon, 07 Sep 2026 17:51:14 +0000

Disclosure: Software Sausage is our product. This is a complete free decision
workflow, not a sponsored ranking. Vendor payments and affiliate availability
do not affect the comparison.

Zapier, Activepieces, and n8n can all move data between applications. They do
not sell the same unit, use the same license, or leave the same operational work
with the customer.

The useful question is not “which has the most connectors?” It is: which
operating model fits one real workflow, and can the team recover or reconstruct
it when something fails?

Start with the billing unit

Pricing pages reviewed September 3, 2026 describe three different units:

Zapier counts successful tasks. Standard actions normally cost one task; some actions and AI model tiers cost more. Its Free plan includes 100 tasks a month, and Professional starts at $19.99 a month billed annually.
Activepieces uses one base credit for one full flow run. Its current Free plan includes 100 credits a day; Plus is $16 a month billed annually with 10,000 monthly credits. AI actions consume additional credits.
n8n counts one complete workflow execution regardless of the number of steps. Cloud Starter is €20 a month billed annually for 2,500 executions; Pro is €50 for 10,000.

A workflow with one trigger and five actions may consume five Zapier tasks but
one n8n execution or one base Activepieces flow-run credit. That sentence is
still not a quote: branches, retries, AI actions, overages, and platform-specific
rules can change the result.

Use a run log from the workflow you actually plan to operate:

monthly cost = platform quote
             + overage units
             + infrastructure
             + monthly operator hours × labor rate

Be exact about open source

Activepieces documents its core under the OSI-approved MIT license and its
enterprise features under a commercial license. The current Community Edition
does not include the whole team and governance layer, so check projects, API,
roles, audit logs, secret managers, and release features against the edition you
will deploy.

n8n is self-hostable and makes its source visible, but n8n itself says the
Sustainable Use License is fair-code and not an open-source license. It
permits internal business use and consulting, while restricting products or
services whose value substantially derives from n8n. If the intended use is
close to that boundary, read the license or obtain a separate agreement.

This distinction matters. “Self-hosted,” “source available,” and “open source”
are not synonyms.

Count the operator

Zapier owns the managed runtime. A self-hosted Activepieces or n8n instance
makes your team responsible for at least:

upgrades and vulnerability response;
the application database and tested restores;
encryption keys needed to recover stored connections;
queue and worker health;
webhook reachability and signing;
credential rotation and least privilege;
run retention, logs, alerts, and on-call ownership;
capacity, concurrency, and rate-limit handling.

Activepieces' current Docker Compose guide, for example, describes an app,
worker, PostgreSQL, and Redis. It explicitly notes that backing up the project
directory does not back up the database, and that the encryption key is needed
to decrypt stored connections after a restore.

None of that makes self-hosting wrong. It makes “free” an incomplete cost
description.

Run a failure test before migrating

Build one representative workflow with test accounts and synthetic records.
Include a branch, a retry-sensitive write, and the real authentication pattern.
Then break it deliberately:

Expire one credential and confirm the alert names the failed connection.
Return HTTP 429 and verify bounded retry and backoff behavior.
Deliver the same webhook twice and verify the final state is idempotent.
Fail a middle step after an earlier system has already been updated.
Exceed the planned usage allowance and record whether work stops or overage charges begin.
Restart the platform or worker and confirm the workflow resumes safely.

A green happy-path run does not establish that a business-critical automation
is supportable.

Run the exit test too

Export the workflow definition using the plan and permission level you intend
to buy. Inspect the export for secrets before storing or sharing it. Import it
into a clean account or instance, then reconnect credentials without copying
secret values into the workflow.

Recreate schedules, webhooks, variables, roles, alert destinations, and any
custom packages. Run the same fixture and reconcile every output and side
effect. Record what required manual rebuilding and how long it took.

Zapier documents JSON workflow import/export for Team and Enterprise accounts,
but app connections still need testing and reconnection. A workflow file from
any platform should be treated as one migration input, not proof that the
operating state moved.

An archive is not a migration. The clean destination has to run.

A practical routing rule

Start with Zapier when managed operations and connector breadth matter more than runtime control, and measured task volume fits the quote.
Test Activepieces when an MIT-licensed core or whole-flow billing is the important constraint, then price the edition and operator work you need.
Test n8n when a technical team wants whole-execution billing and its source-available license and hosting model fit the intended use.

No product wins this decision in the abstract. The failure and reconstruction
evidence should decide.

Primary sources:

The free inventory, failure drill, exit worksheet, and verifier are in the
Software Sausage recipes repository.

The complete dated guide is at
Software Sausage.
The free kit and shortlist require no email; the optional report and integrator
request are separate paid or consent-based actions.

The graph is not the trust layer

Constantine Macris — Thu, 03 Sep 2026 23:08:33 +0000

Disclosure: Software Sausage is our product. Blake McCarn did not sponsor, review, or endorse this article. AI tools helped draft and edit it; the evidence boundaries are stated below.

The graph is not the trust layer

Blake McCarn's Paperless Knowledge Graph is not interesting merely because it lets someone chat with scanned documents. The stronger idea is that retrieval leaves evidence behind and can refuse to answer when that evidence is weak.

This is a source review, not a field test. We reviewed McCarn's case study, inspected the current public repository, and checked related projects. We did not connect the stack to his private archive or reproduce its reported accuracy, scale, speed, or cost.

The pipeline

Paperless source documents
  → baseline OCR → selective enhanced OCR
  → classify → extract → verify → relate
  → graph + vector + keyword indexes
  → quick | deep | timeline | strict query
  → cited answer + claim ledger + trace

McCarn reports more than 800 documents, roughly 7,000 graph nodes, 25,000 relationships, and 6,000 searchable chunks. Those are author-reported results, not Software Sausage measurements.

Five decisions worth carrying into other systems

1. Preserve the source of truth

Paperless remains the document authority. Enhanced OCR runs as a companion layer, so the archive is not held hostage by the AI pipeline.

2. Compare identities, not counts

The freshness check compares exact document ID sets and hashes across Paperless, Neo4j, and vector chunks. Equal counts can still conceal one missing document and one stale replacement.

3. Route by question shape

Entity lookups use the graph. Deeper questions combine vector, keyword, and graph retrieval. Timeline mode keeps dates explicit. Strict mode can refuse weak evidence instead of filling the gap with confident prose.

4. Leave inspectable artifacts

The repository includes evidence-pack, claim-ledger, trust-dimension, trace, and answer-repair paths. A separate model pass may catch inconsistencies, but it is not independent ground truth. The verifier can share the drafter's blind spots.

5. Put model routing outside the app

LiteLLM centralizes model aliases, credentials, limits, and cost visibility. That reduces provider coupling; it does not eliminate the need to test authentication and response behavior end to end.

What the public repository proves

The source contains the advertised evidence helpers, exact-drift audit, API smoke checks, and an evaluation harness for fixed questions. Its published container workflow is green, but it builds images rather than gating publication on those checks.

The Python dependency file is mostly unpinned. The README says MIT, while the repository had no LICENSE file and GitHub detected no license when we reviewed it. Until that is corrected, treat the code as publicly readable rather than reusable MIT material.

Most importantly, no public fixture establishes the accuracy implied by its medical, tax, financial, and legal query modes. Strict refusal and visible citations are useful controls. They do not replace opening the source.

The wider process is consistent

Portable Brain applies the portability boundary to knowledge work: plain Markdown, YAML, and relative links remain useful without a runtime, while source evidence stays separate from synthesized notes. We ran its current test suite locally: 75 tests passed. A full-repository lint also found one executable-bit issue in an optional Paperless integration outside the project's narrower CI lint scope.

McCarn's Herdr write-up separates terminal topology from provider logic: one worktree per implementation, distinct review and test surfaces, and status labels used for routing rather than proof. His LiteLLM operating note makes a similar boundary explicit for model traffic, budgets, and credentials.

The field test we should run

Build a synthetic, non-sensitive Paperless archive with ordinary text, tables, handwriting, duplicate entities, contradictory dates, and one deliberately stale index. Freeze a dozen questions and score source coverage, exact-value accuracy, unsupported claims, refusal behavior, elapsed time, and model cost.

Then remove one document, add another so the total count stays equal, and require the exact freshness check to catch the swap.

That would turn a strong architecture story into a reproducible recipe. Until then, the honest label is community source review.

Read the complete review and follow the proposed verification run at Software Sausage.

Six open-source AI workflow kits you can actually inspect

Constantine Macris — Thu, 03 Sep 2026 22:20:44 +0000

Disclosure: Software Sausage is our product and publishes these recipes. The kits are free and MIT-licensed. AI tools helped draft and edit this article; the workflow status and evidence limits are stated below.

Most AI workflow lists answer the easiest question: which tools can be placed next to each other in a diagram?

We wanted to answer a harder one: what evidence should remain after the tools finish?

That produced six small workflow kits. Each one contains a README, an editable evidence ledger, and a dependency-free shell verifier. All 17 verifiers in the repository pass at release v0.17.0.

That is a structural claim, not a performance claim. The checks prove that the required files and fields exist. The new workflows remain explicitly marked “not benchmarked” until measured runs are published.

1. Specification to production proof

Use GitHub Spec Kit to freeze the outcome, exclusions, acceptance criteria, and rollback boundary. Let one coding agent implement the reviewed tasks. Then run existing checks plus a small user-flow proof and ask a different model to compare the result with the original specification.

The artifact is not a generated plan. It is the linked specification, reviewed diff, executable checks, browser evidence, and rollback note.

2. AI workflow regression test

Freeze representative success, edge, and refusal cases before changing a prompt, model, tool, or instruction file. Promptfoo can run the baseline and candidate against the same cases while retaining assertions, latency, token use, cost, and failures.

Prefer deterministic assertions before model grading. Also isolate the run: Promptfoo configurations can execute code and are not a sandbox.

3. Open-source coding-agent benchmark

Pick one real repository task and define hidden acceptance checks. Pin the harness, model endpoint, instructions, permissions, tools, and context budget. Run Qwen Code, Goose, OpenCode, or another candidate from fresh copies at least three times, then blind the labels before reviewing the artifacts.

The result should select a configuration for that job and environment, not declare a universal winner.

4. Document-parser fidelity test

Run MarkItDown and Docling on the same authorized documents. Score the raw output for ordering, tables, citations, omitted text, OCR errors, and usable source locations before giving it to a model.

A fluent summary cannot repair a missing table cell. Reopen every decision-changing number, date, obligation, and citation in the source.

5. Browser performance regression

Freeze the browser, viewport, data state, network conditions, and user action. Use Playwright to reproduce the flow and Chrome DevTools MCP to retain a trace, console output, and relevant network evidence. Make the smallest root-cause fix, then rerun the same conditions several times.

One lab trace is not field performance. Keep authenticated browser profiles away from an MCP client unless that access is deliberately required.

6. Safe dependency upgrade

Let Renovate propose a narrow update. Record the direct and transitive changes, lockfile diff, release notes, supported runtime range, and rollback version. Use OSV-Scanner and Semgrep as review inputs, then run the project's actual checks and a representative runtime flow.

Clean scans do not prove compatibility or the absence of vulnerabilities.

Try to break one

Every kit is available in the pinned v0.17.0 release. Run one on a disposable fixture. If its verifier passes while decision-critical evidence is missing, open an issue with the smallest safe reproduction. That is more useful than a star.

The readable library and the boundary for each workflow are in Software Sausage.

Primary references: GitHub Spec Kit, Promptfoo assertions, Qwen Code, Goose, Chrome DevTools MCP, MarkItDown MCP, Renovate, and Semgrep CLI.

A source-led research-paper workflow with Obsidian, Claude Code, LaTeX, and Codex

Constantine Macris — Wed, 02 Sep 2026 14:48:34 +0000

Disclosure: AI tools helped draft and edit this article. A human publisher reviewed the final text and workflow before publication.

Putting four tools in a list does not make a workflow. The difficult part is
deciding which tool owns each artifact, what the next tool may change, and what
must still be checked by a person.

This recipe uses four bounded roles:

Obsidian keeps the source ledger, claim status, notes, and open questions in readable Markdown.
Claude Code works across the outline and manuscript files while material factual claims remain tied to ledger IDs.
LaTeX owns the versionable manuscript, bibliography, equations, and build warnings.
Codex acts as a separate critic of the ledger, manuscript diff, and build log. It is not treated as evidence.

The objective is not automatic authorship. It is a manuscript whose claims,
sources, build, and review trail remain inspectable.

Start with files, not a blank chat

paper-project/
├── sources/              # permitted PDFs, links, and notes
├── brief.md              # question, audience, scope, deadline, rules
├── source-ledger.md      # claim -> citekey -> verification status
├── outline.md
├── manuscript.tex
├── library.bib
└── review-findings.md

You can clone the starter repository:

git clone https://github.com/Software-Sausage/recipes.git sausage-recipes
cd sausage-recipes/recipes/research-paper

Work in a private copy when the paper or source set is not public. The
sources/ directory is ignored by Git, but an ignore rule is not a substitute
for checking what your agent, sync service, and plugins can access.

1. Write the brief yourself

Fill in brief.md before asking a model to draft anything. State the research
question, audience or venue, thesis, permitted sources, citation style,
deadline, institutional AI-use rules, exclusions, and claims that require
specialist review.

If those decisions are missing, fluent prose only hides the ambiguity.

2. Make the source ledger the control surface

Create one row for every material claim:

| ID | Claim | Citekey | Page/section | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| C-001 | ... | ... | ... | UNVERIFIED | ... |

The author—not the agent—changes UNVERIFIED to VERIFIED after opening the
source and checking the cited passage. An abstract, metadata record, search
snippet, or model summary is not source verification.

3. Hand the ledger and outline to the drafting agent

Ask Claude Code to inventory only the permitted source files, build the ledger,
and draft the argument in outline.md before editing prose. Require ledger IDs
beside material claims. Unsupported claims stay visible as questions; they do
not get smoothed into confident paragraphs.

The starter AGENTS.md also tells the agent not to browse, download, upload,
publish, or contact anyone unless the author explicitly authorizes it.

4. Keep the build evidence

Draft manuscript.tex and library.bib from the checked outline. Run:

./verify.sh

The script checks that the required artifacts exist and builds the manuscript
when latexmk is available. Before review, run:

./verify.sh --final

The final check rejects remaining TODO, UNVERIFIED, and UNRESOLVED
markers. Do not weaken the check to make a run green.

5. Use a different model as a critic

Give Codex the brief, source ledger, manuscript diff, bibliography, and build
output. Ask it to record unsupported claims, broken references, logical gaps,
and reproducibility failures in review-findings.md.

This is a critique, not independent fact verification. Two model families can
repeat the same error. The author still opens every cited source and resolves
each material finding.

Definition of done

The paper is ready for author review when:

the manuscript compiles;
bibliography links and build warnings have been reviewed;
no material claim remains unverified;
the review log shows each finding and resolution; and
the author has confirmed the venue's authorship and AI-use rules.

Open-source substitutions

LaTeX and the recipe itself are open source. If proprietary tools are a bad fit,
test Zettlr or Logseq for Markdown notes and Aider or OpenHands for repository
work. Treat these as substitutions to verify, not drop-in compatibility claims;
the same fixture and final checks should be rerun after changing a tool.

If you try the recipe, report the first confusing or broken step in the
starter repository.
Failures are the useful part of this stage.