documents: codebook.md

The exact instructions every agent role received (briefs), the verification prompt, the extraction protocol, screening criteria and the release datasheet.

Data license: Not yet licensed — internal review only · Data source: Ahmed ElBatanony, Innopolis University

This data as json

name	text
codebook.md	# pub-10 capability codebook — v0.1 (iteration 0, nothing confirmed yet) > The machine-readable twin is [codebook.json](codebook.json). `tools/business-apps/records.ts` rejects any coded feature whose capability code is not listed there. > > Rule zero: no SQ5 vocabulary. Capability names describe what an application offers its users, in domain-neutral language. They never use the names of any platform's primitives (SQ5's node types included), because the later coverage study (pub-9) measures SQ5 against this taxonomy. ## 1. Meta-characteristic The functional capability an application offers its users, independent of business domain and of implementation technology. A capability is something a user can make the application do (record, route, schedule, compute, show, notify, exchange, expose). Excluded: qualities (fast, secure, scalable), deployment and licensing facts, and the business domain itself ("for dentists"). ## 2. Unit of analysis: the feature statement One user-observable capability, in one of two forms: > The system lets ⟨actor⟩ ⟨action⟩ ⟨object⟩ [⟨condition⟩] — something a user does > > The system automatically ⟨action⟩ ⟨object⟩ when ⟨event⟩ — an automation The pilot showed automations are common (29 of 224 statements had to be rewritten into the second form) and are a capability in their own right, so they get their own form instead of being forced into "lets". \| Rule \| Example source text \| Statement(s) \| \|---\|---\|---\| \| One capability per statement; split conjunctions \| "Create, send and track quotes" \| lets a salesperson create a quote · send a quote to a customer · see a quote's status \| \| Keep conditions; they are often the capability \| "Invoices above the limit need manager approval" \| lets a manager approve an invoice whose amount exceeds a threshold \| \| The actor is a role, not a person; use "a user" if unstated \| "Track your inventory" \| lets a user see stock levels per item \| \| Drop marketing qualifiers \| "Blazing-fast, beautiful reports" \| lets a user view a report \| \| Not a capability → no statement (record it as a skipped excerpt) \| "Trusted by 10,000 teams", "GDPR compliant", "Self-hosted" \| — \| \| Integrations name the kind of exchange, not the vendor \| "Sync with QuickBooks" \| lets a user exchange accounting records with an external accounting system \| \| Automations use the second form; the actor is the system \| "Jobber automatically sends visit reminders" \| automatically sends a visit reminder to a client before a scheduled visit \| \| One capability is recorded once per application; keep the first excerpt \| A page that lists every feature twice \| one statement \| \| Testimonials, case studies and customer stories are never evidence \| "Acme runs multi-state payroll in under 1 hour" \| — (skip, reason `testimonial`) \| \| Claims about the platform an app is built on are not the app's capabilities \| Template page: "fully customizable with a drag-and-drop builder" \| — (skip, reason `platform`) \| \| IT-infrastructure administration that no business role uses \| "Access to root shell", "SNMP monitoring", "server clustering" \| — (skip, reason `deployment`) \| \| User-facing sign-in and access features are capabilities \| "Two-factor authentication", "single sign-on" \| lets a user sign in with a second factor \| \| Do not infer beyond the excerpt \| "device logging" \| — not "lets an administrator see login devices" \| Skip reasons: `quality`, `compliance`, `deployment`, `pricing`, `social-proof`, `testimonial`, `platform`, `other`. ## 3. Coding rules - A statement gets one or more capability codes. Use more than one only when the statement genuinely needs both (e.g. an approval that also notifies). - Code what the statement says, not what an implementation would need. - If no code fits, write a memo proposing a new capability with a definition and the statement as its anchor. New codes are added only at the end of an iteration, never mid-batch. - Every change to this file is logged in §6 with the iteration number and the reason. ## 4. Ending conditions (Kundisch et al. 2022, after Nickerson et al. 2013) Objective: - every statement in the build set is coded; - the last iteration added, merged or split no capability or family; - every capability has at least one statement; - every family has at least two capabilities. Subjective: concise, robust, comprehensive, extendible, explanatory. These are assessed by the authors and then by the expert panel. ## 5. Families: deductive candidates (iteration 0) These are hypotheses from established frameworks, to be confirmed, merged, split or dropped by the first empirical iteration. None has capabilities yet. That is deliberate: capabilities come from the data. \| Code \| Family \| Seed source \| \|---\|---\|---\| \| REC \| Records and their lifecycle \| Business archetypes (party, product, order, inventory: Arlow & Neustadt); CRUD \| \| PROC \| Process and workflow \| Workflow patterns (van der Aalst et al.) \| \| ACC \| Access and accountability \| RBAC/ABAC; audit trails \| \| TIME \| Time, scheduling and recurrence \| Booking and scheduling prominence in the seed scan \| \| CALC \| Calculation and money \| Archetypes (quantity, money) \| \| INFO \| Presentation, reporting and documents \| Platform literature \| \| COMM \| Communication and notification \| Platform literature \| \| INT \| Integration and data exchange \| Platform literature \| \| EXT \| External parties and self-service \| Portals, public forms, e-signature \| ## 6. Change log \| Version \| Iteration \| Change \| Reason \| \|---\|---\|---\|---\| \| 0.0 \| 0 \| Families seeded as candidates; no capabilities \| Conceptual-to-empirical start (Kundisch et al.) \| \| 0.1 \| 0 \| Automation statement form; once-per-app rule; testimonial, platform and IT-operations skip rules; sign-in features count; no inference \| Pilot (17.10.2026), see `pilot/README.md` and `pilot/verification/` \|

name

text

codebook.md

# pub-10 capability codebook — v0.1 (iteration 0, nothing confirmed yet) > The machine-readable twin is [codebook.json](codebook.json). `tools/business-apps/records.ts` rejects any coded feature whose capability code is not listed there. > > **Rule zero:** no SQ5 vocabulary. Capability names describe what an application offers its users, in domain-neutral language. They never use the names of any platform's primitives (SQ5's node types included), because the later coverage study (pub-9) measures SQ5 *against* this taxonomy. ## 1. Meta-characteristic *The functional capability an application offers its users, independent of business domain and of implementation technology.* A capability is something a user can make the application **do** (record, route, schedule, compute, show, notify, exchange, expose). Excluded: qualities (fast, secure, scalable), deployment and licensing facts, and the business domain itself ("for dentists"). ## 2. Unit of analysis: the feature statement One user-observable capability, in one of two forms: > **The system lets** ⟨actor⟩ ⟨action⟩ ⟨object⟩ [⟨condition⟩] — something a user does > > **The system automatically** ⟨action⟩ ⟨object⟩ **when** ⟨event⟩ — an automation The pilot showed automations are common (29 of 224 statements had to be rewritten into the second form) and are a capability in their own right, so they get their own form instead of being forced into "lets". | Rule | Example source text | Statement(s) | |---|---|---| | One capability per statement; split conjunctions | "Create, send and track quotes" | lets a salesperson create a quote · send a quote to a customer · see a quote's status | | Keep conditions; they are often the capability | "Invoices above the limit need manager approval" | lets a manager approve an invoice whose amount exceeds a threshold | | The actor is a role, not a person; use "a user" if unstated | "Track your inventory" | lets a user see stock levels per item | | Drop marketing qualifiers | "Blazing-fast, beautiful reports" | lets a user view a report | | Not a capability → no statement (record it as a skipped excerpt) | "Trusted by 10,000 teams", "GDPR compliant", "Self-hosted" | — | | Integrations name the *kind* of exchange, not the vendor | "Sync with QuickBooks" | lets a user exchange accounting records with an external accounting system | | Automations use the second form; the actor is the system | "Jobber automatically sends visit reminders" | automatically sends a visit reminder to a client before a scheduled visit | | One capability is recorded **once per application**; keep the first excerpt | A page that lists every feature twice | one statement | | **Testimonials, case studies and customer stories are never evidence** | "Acme runs multi-state payroll in under 1 hour" | — (skip, reason `testimonial`) | | Claims about the **platform an app is built on** are not the app's capabilities | Template page: "fully customizable with a drag-and-drop builder" | — (skip, reason `platform`) | | IT-infrastructure administration that no business role uses | "Access to root shell", "SNMP monitoring", "server clustering" | — (skip, reason `deployment`) | | User-facing sign-in and access features **are** capabilities | "Two-factor authentication", "single sign-on" | lets a user sign in with a second factor | | Do not infer beyond the excerpt | "device logging" | — not "lets an administrator see login devices" | Skip reasons: `quality`, `compliance`, `deployment`, `pricing`, `social-proof`, `testimonial`, `platform`, `other`. ## 3. Coding rules - A statement gets **one or more** capability codes. Use more than one only when the statement genuinely needs both (e.g. an approval that also notifies). - Code what the statement **says**, not what an implementation would need. - If no code fits, write a **memo** proposing a new capability with a definition and the statement as its anchor. New codes are added only at the end of an iteration, never mid-batch. - Every change to this file is logged in §6 with the iteration number and the reason. ## 4. Ending conditions (Kundisch et al. 2022, after Nickerson et al. 2013) **Objective:** - every statement in the build set is coded; - the last iteration added, merged or split no capability or family; - every capability has at least one statement; - every family has at least two capabilities. **Subjective:** concise, robust, comprehensive, extendible, explanatory. These are assessed by the authors and then by the expert panel. ## 5. Families: deductive candidates (iteration 0) These are **hypotheses from established frameworks**, to be confirmed, merged, split or dropped by the first empirical iteration. None has capabilities yet. That is deliberate: capabilities come from the data. | Code | Family | Seed source | |---|---|---| | REC | Records and their lifecycle | Business archetypes (party, product, order, inventory: Arlow & Neustadt); CRUD | | PROC | Process and workflow | Workflow patterns (van der Aalst et al.) | | ACC | Access and accountability | RBAC/ABAC; audit trails | | TIME | Time, scheduling and recurrence | Booking and scheduling prominence in the seed scan | | CALC | Calculation and money | Archetypes (quantity, money) | | INFO | Presentation, reporting and documents | Platform literature | | COMM | Communication and notification | Platform literature | | INT | Integration and data exchange | Platform literature | | EXT | External parties and self-service | Portals, public forms, e-signature | ## 6. Change log | Version | Iteration | Change | Reason | |---|---|---|---| | 0.0 | 0 | Families seeded as candidates; no capabilities | Conceptual-to-empirical start (Kundisch et al.) | | 0.1 | 0 | Automation statement form; once-per-app rule; testimonial, platform and IT-operations skip rules; sign-in features count; no inference | Pilot (17.10.2026), see `pilot/README.md` and `pilot/verification/` |