# Nacodex Contribution Guide

For external contributors: load this file at the start of a working session, or paste it to your AI assistant. **Loading it starts no work.** During the session it asks two things: follow Rule 1, and keep rough notes. The real work — the **sweep** (Part 1), then **Write** (Part 2) if the sweep finds anything — runs once, at the end. Loaded partway through or at the end? Sweep everything before that point; missing notes are fine. Rule 1 governs only what you write for Nacodex, not your project work.

## Rule 1 — Privacy, both directions (read first)

- **What you get:** how to recognize and describe an engineering discovery. How Nacodex classifies, stores or scores submissions is not shared, and you never need to match anything against it. Describe the problem and the solution in your own words; placing it is our work.
- **What we ask in return:** nothing identifying. No personal, employer, client, product or project names; no internal URLs, hostnames, IP addresses, or paths that reveal your repository or organization; no keys, tokens, secrets or credentials. The only identifying detail is your contributor ID — the email address you send it from (see Part 2).
- **Your email address stays with us.** It is your contributor ID, used only to recognize your submissions and to reply — it is never written into Nacodex itself or anything published, only into the file you personally send. Send from a personal address — a work address reveals your employer.
- **When in doubt, leave it out.** Describe the *shape* of the problem instead of redacting the specific thing. Slightly less precise is always acceptable; a detail that slips through is not.
- **It covers everything** — prose, code, error messages, filenames, screenshots. Paraphrase what people said; never quote. Give times as relative ("seconds apart", "the next day"), never as dates or clock times from the work.
- **Public technology names are allowed where the lesson depends on them** — a language, framework, database, operating system, protocol or public service; "SQLite in WAL mode" keeps a point "a database" loses. Never name internal tools, private libraries, your own products, or your employer's or client's accounts, endpoints or configuration. If the technologies you name would together point to one company or product, generalize one. A platform or protocol others build on (a blockchain, a wallet-connection standard) is a public technology; a consumer app (a particular wallet, browser or launcher) is named only when the lesson is that app's own behaviour — otherwise its class: "a mobile wallet", "a privacy-focused browser".
- **No source code from your project, even generalized.** Show a shape with an invented sketch: a few lines, pseudo-code preferred, no identifier, file or function name from the project.
- **No business figures** — user counts, revenue, prices, volumes, catalogue sizes, number of supported languages. Use a ratio or a shape ("under half of active users", "a few dozen"). Technical measurements and setting values (a timeout, a page size, a request limit) are fine; the host or file they live in is not.
- **Security weaknesses: the class, never the recipe.** If one is still open — including when this instance is fixed but the mechanism remains — write only "a security weakness in [general area], still open" under *Security*, and nothing elsewhere in the file may describe how to reach it.

---

## Part 1 — Detect

### What counts

Nacodex is a knowledge base of patterns, dead ends and hard-won rules from real software work. The test for any event: **would this plausibly bite someone else, in a different project, doing something structurally similar?** If yes, it counts — even a small one.

- **Pattern** — a reusable solution with a name, a "use this when", and a shape. *Example: derive a value from its single source where it is used, instead of caching a copy that drifts.*
- **Dead end** — an approach structurally incapable of working; say why. *Example: a fixed delay over a race passes tests and fails under load, because it hides the race.*
- **Axiom / hard constraint** — break it and a specific failure reliably follows. *Example: a fact stored in two layers needs exactly one write path.*
- **Scope boundary** — a rule that normally works, applied where it does not hold; state the exact condition. *Example: a caching rule right for slow-changing data serves stale results on data that changes every few seconds.*
- **Process insight** — something about *how* the work was done that generalizes. *Example: the answer was in a reference doc nobody consulted until after the mistake.*

### During the session — rough notes

When something looks like it counts, note it before continuing — in the conversation, where the sweep will re-read it, or in a personal scratch file. Never in project files.

```
[NACODEX-NOTE]
What happened: <one or two sentences>
Evidence: <error text without names or paths, a measured value, or what was said in substance>
Confidence: High / Medium / Low
```

**High** — seen more than once, or reproduced. **Medium** — once, with a solid explanation. **Low** — suspected. Any level counts. Notes help, but they are not the detection: most discoveries are visible only in hindsight, where every step looked successful. **The sweep catches them.**

### End of session — the sweep (every session)

**Human:** end every session with *"run the NACODEX sweep"* — a session closed without it was never swept. **AI assistant:** run it on that sentence or when the session is ending, yourself, from the session — don't ask the human what happened.

**Step 1 — Re-read the whole session** from the first message, not from memory or a summary; memory keeps outcomes and drops the detours where discoveries are. If the session was already swept, start where that sweep ended — unless its output was discarded or a full rerun is asked for.

**AI assistant:** re-read this session's raw log where one exists and you are permitted to read it — chosen by session, not by newest file; the conversation in front of you may already be a summary. A log that exists but sits outside what you may read is a gap, not a reason to widen access: re-read the conversation and say so in *Coverage*. A long log may be reduced to every human message, assistant message, command and error, read in full. **Messages the human sent while you were working are often stored apart from ordinary turns** (for example as queued entries): print one raw record to find where, and include them — they often carry the corrections. **Trace every specific factual claim back to this session's own output before writing it down** — a similar-looking detail read from a different record earlier in the same session is a claim to verify, not an observation of this one; re-check against the actual current transcript rather than a recalled impression of it.

Record in *Coverage*: where the re-read began, what you read and any reduction, the number of human messages (typed by the human — not interruption markers or notices), the earlier sweep's file if any, and every gap. A stated gap beats a summary that claims full coverage.

**Step 2 — Inventory every event**, one line per symptom or event, with attempt counts inside the line; routine edits fold into their task's line. No filtering:
- every error, crash, failed build or test, wrong output
- every fix attempt, counted per symptom
- every correction, rejection or repeated request from the human
- every rule or preference the human stated — "always", "never", "from now on", "only when…"
- every surprise
- every risky or destructive action, stopped or not
- every workaround, temporary change, disabled check or hard-coded value
- every choice the assistant made that the human never asked for or approved
- every claim that something is done, fixed, verified or safe

**Step 3 — Ask every line seven questions.** *Does not apply* is a valid answer; *don't know* is not — it means the line is not understood yet. The answers are working notes; only the verdicts reach the output.
1. **Could the check have failed?** A passing test, an empty search, a screenshot, a dry run — did it examine the real thing, or would it have passed either way?
2. **What kind of evidence was it?** Handling code is not proof the case happens; a remembered value is not a looked-up one; a sample is not the set when the set could be checked; "never" and "always" from a few observations are guesses.
3. **Fixed one — where are the others?** What else reads the source that was read wrongly? A bug that "comes back" through separate reports is usually one bug with several sites.
4. **Which assumption expired?** Single became plural; a fixed list gained a member; a different part now writes the value; "keep in sync" with nothing enforcing it; a limit built for one use now serves another.
5. **Did something temporary stay?** A debug change; a fallback that invented a value instead of failing; an "unknown" cached as fact.
6. **Is a risk handled only on paper?** A named safeguard that is not switched on; an estimate made while its inputs were still arriving.
7. **Was something closed without being resolved?** "Working as designed" without checking; a choice that ignored something the human had already said; the same misunderstanding corrected twice.

**Step 4 — Give every line a verdict: NOTE or SKIP.** A SKIP needs one of these reasons, fitting plainly:
- a one-off slip or environment event with no cause in how the work was done (a typo, the machine out of memory) — if it could happen again tomorrow on the same task, it has a cause and is a NOTE
- a content decision the **human** made about what the product says or does (wording, numbers, colours, scope), including changing their mind — a choice the assistant made on its own is a NOTE
- the human only confirmed something that already worked
- already covered by another NOTE (say which)
- caught before shipping by a check that did its job — pre-existing, or written during the session before anything slipped through — with nothing new about the check; a check written after the problem slipped through makes it a NOTE
- went as expected, with no correction, surprise or retry — a routine request, or a check that passed and **could have failed** (say how)

Anything else, or a stretched reason, is a NOTE. Problems with this guide are neither: add a line for each one (including during the sweep) under *Guide feedback*, for the version you are following.

**Never skippable** — always a NOTE, with its status, at Low confidence if need be:
- a bug still open at session end
- a fix or new code not verified by running the changed code path — a build, compile, syntax check or unrelated test does not count; a run the human reports counts if you attribute it; where nothing could run, one line per area marked "unverified — could not run"
- a symptom that took three or more fix attempts
- a mistake that recurred after its lesson was written down — in notes, a rule, an earlier submission or sweep, even unsent
- a line where a Step 3 question got *don't know*

A line without a verdict means the sweep is not finished. An empty inventory in a session that changed code means Step 1 was skipped.

**Step 5 — Group and order.** Bundle NOTEs that share a root cause into one discovery; split any whose rule needs unrelated points — one discovery, one lesson. *Bundle:* three failures from the same escaping layer. *Split:* an escaping failure and a missing folder. A NOTE that happened once, is Low confidence and has a one-line rule goes under *Minor notes* instead — never a never-skippable one. A still-open security weakness is one line under *Security*. Bundled never-skippable NOTEs keep their status. Every inventory line counts in N once, guide feedback and security lines included. Order discoveries: security or data loss, then user-visible breakage, then lost time; ties by recurrence, then confidence. No discovery → nothing to send.

---

## Part 2 — Write

**File:** `Nacodex_Contribution_<ContributorID>_<YYYY-MM-DD_HHMM>.md` — your ID and the local time the file is written. Your ID is your email address, written filename-safe (replace `@` and `.` with `_`), e.g. `Nacodex_Contribution_jane_at_example_com_2026-09-14_1530.md`. **In English**, whatever language the session used.

**Where:** outside the project repository and working folder, so it is never committed or synced with project files. **AI assistant:** use the location the human gave, including earlier in the session. For the ID, use the human's email address only if they've already given it to you in this session — otherwise leave `[your email address]` as a placeholder for the human to fill in before sending; don't guess or invent one. Write a scratch copy for the privacy search (it needs a file); write elsewhere only where asked. Print the finished file in the chat with its filename when it fits; if it is too long to read there, print the Quick summary and the discovery titles and say where the file is. Where the ID is still unknown, use `FILL_IN_ID` in the filename; the human renames the file when filling in the field.

**Whatever format you are asked to answer in** — one block, an app's form, a short reply — the method stays whole: run the sweep and the privacy search first, then put the complete output file below inside that format. A requested title is Discovery 1's title. A format never turns the sweep into one picked incident.

**AI assistant: no number before its output.** Every count, search result and status in the file comes from something run in this session — a count you made, a search you ran. A step you did not do reads `NOT RUN — <reason>`; it is never filled in from expectation.

### Your contributor ID

Simple: **it's the email address you send this from.** Nothing assigned, nothing to wait for. Put that same address in the `Contributor ID` field of every file, exactly as it appears in your email's "From." Every submission from that address is recognized as yours automatically. Sending from a different address later is simply a new, separate ID from our side — mention your earlier address in the file if you want the two linked.

**Sending through the Nacodex app instead?** Its sign-in identifies you: write `Nacodex Help app` in the Contributor ID field and `app` in the filename, skip the email steps, and share the answer back to the app.

### Interview — per discovery, generalized

**AI assistant:** answer from the sweep and the session; ask the human only what the session does not show. The answers fill the template.
1. The general problem or symptom — domain-level ("background sync in a mobile app").
2. What was tried, and why each attempt failed structurally.
3. What was actually **observed**, kept apart from what you concluded.
4. The root cause, and why the symptom did not reveal it.
5. The reusable rule — its name, where it applies, **where it does not**, its minimal shape.
6. How someone would catch it next time.
7. Status — verified (which run, whose), partly verified, unverified, or still open.
8. Confidence, and why.
9. Written down or reported before? How many times has it now happened?

### Output file — template

The finished file opens with a short, plain-language block for the human sending it — the counts, the safety confirmation, and the send steps already covered below, just moved ahead of the technical body so nothing has to be hunted for. **AI assistant:** fill it last, after the privacy search, from the finished Sweep summary, Coverage and Contributor ID — it introduces nothing new.

```markdown
# Nacodex_Contribution_<ContributorID>_<YYYY-MM-DD_HHMM>

## Quick summary — read this first
[D discoveries, M minor notes, W security-sensitive lines. Privacy check, from the Run 2 output: clean (0 terms) — or NOT RUN. Name every step the Sweep ledger marks NOT RUN. Run counts are in Coverage below if you want them.]

**To send it:**
1. Fill in `Contributor ID` below with the email address you're about to send this from — that's your whole ID, nothing to wait for.
2. Attach this whole file, unedited, to an email to **nacodex@pukapasoft.xyz**
3. Subject: `Nacodex Contribution — [Contributor ID] — [D] discoveries — [title of Discovery 1]`
4. Send whenever you're ready — every submission gets a reply, no fixed timeline.

Everything below this line is the technical write-up Nacodex's reviewers use — worth a skim, not required reading.

---

## Contributor ID
[the email address you are sending this from]

## Date
[YYYY-MM-DD]

## Sweep ledger
[One line per step: RUN with its result, or NOT RUN — reason.
Step 1 re-read: where it began, human messages and how they were counted
Step 2 inventory: N lines
Step 3 seven questions: RUN or NOT RUN
Step 4 verdicts: K notes, S skipped, G guide feedback
Step 5 group: D discoveries, M minor notes, W security lines
Privacy search: control result, Run 1, Run 2]

## Sweep summary
[N inventory lines — K notes, S skipped, G guide feedback (K + S + G = N) — D discoveries, M minor notes, W security lines]

## Coverage
[Where the re-read began; what was read and any reduction; the number of human messages; the earlier sweep's file, if any; gaps. Privacy search: control result, Run 1 (N terms, M fixed), Run 2 (N terms, 0).]

## Skipped lines
[One generalized line per SKIP with its Step 4 reason, so a reviewer can catch a skip that should have been a note.]

## Security
[Only if a weakness is still open — one line each: "a security weakness in [general area], still open". Otherwise omit.]

## Discovery 1 — [one-line title]

### Covers
[The NOTE lines bundled here, one short generalized phrase each.]

### Problem Domain
[One general line, e.g. "mobile app state management".]

### Discovery Type
[Pattern / Dead End / Axiom or Constraint / Scope Boundary / Process Insight / combination]

### Status
[Fixed and verified — which run, yours or the human's / Partly verified — which part ran / Fixed, unverified / Still open]

### Confidence
[High / Medium / Low — one sentence why]

### Reported before
[No / Yes — where, and how many times it has now happened]

### Symptom
[What went wrong, as a shape — not the specific system.]

### Evidence
[What was observed — error text without names or paths, measured values, what was said in substance. No interpretation.]

### What Was Tried
[Numbered; one sentence per approach on why it failed structurally.]

### Root Cause / Structural Insight
[The actual cause, and why the symptom did not reveal it.]

### Pattern or Rule
[Name, definition, when it applies.]

### Where It Does Not Apply
[Conditions under which the rule is wrong or unnecessary.]

### How to Catch It
[The check, search or signal that would have surfaced it earlier.]

### Example
[Minimal invented sketch, never copied from real code. Optional for a Process Insight — a checklist or before/after sentence will do.]

### Submitter Notes
[Uncertainty, alternative readings, related things not chased.]

## Discovery 2 — ...
[Repeat per discovery, strongest first.]

## Minor notes
[One line each: what happened, generalized — the one-line rule.]

## Guide feedback (optional)
[Anything in this guide that was unclear, missing or wrong while you followed it.]
```

### Before you send it — privacy search (required)

Reread the whole file as a stranger would, skipped lines and email subject included: could anything identify your employer, your product or a real person? Generalize it.

**AI assistant:** build the term list from the session, not from memory — every proper name, identifier, path, host, business figure and quoted phrase. Then:
- **Control** — run the search once over a text known to contain some of the terms, such as the session log or a scratch file with a few terms pasted in. It must find matches. If it finds none, the search itself is broken; fix it before trusting any zero. No such text? Say so in *Coverage* and treat every zero as unverified.
- **Run 1** — search the file for every term; generalize or remove every match.
- **Run 2** — search the saved file again with the full list. It must return 0; on any match, fix and run again.

Search project terms as whole words; a common word used in its ordinary sense may stay — note it. Fill the control and both runs into *Coverage* last, from the actual output. Without them the file is unchecked.

### How to submit

**The human sends it; an AI assistant never sends anything.** Attach the file to an email:

Email: **nacodex@pukapasoft.xyz**
Subject: `Nacodex Contribution — [Contributor ID] — [D] discoveries — [title of Discovery 1]`

Every submission is reviewed against the current Nacodex edition, and qualifying ones are folded in. You get a reply either way. Small, best-effort project — no timeline.

---
Nacodex Contribution Guide — v3.4 — 2026-10-07 — Questions: nacodex@pukapasoft.xyz