Skip to content

Position Paper

Purpose

Answers: What do we think about this, why should the audience agree, and what would make us wrong? It takes a side. It is not tied to one client.

Example

Show a worked example of this artifact
---
ddx:
  id: PP-001
  type: position-paper
  authoring:
    home: repo
  links:
    - {id: TA-001, kind: supported_by, rev: example}
    - {id: component-profile-python-reusable, kind: supported_by, rev: example}
recommendations:
  - subject: component-profile-python-reusable
    label: Python
    context: repository-tooling
    stance: conditional
    conditions: The repository already uses Python and no script needs a Node.js-only library.
    rationale: One runtime is less to install and maintain than two, and the cited assessment finds the two comparable for text and file work.
    based_on: [{assessment: TA-001, criteria: [text-and-file-handling]}]
    since: 2026-11-06
    review_by: 2027-02-06
weights:
  - criterion: text-and-file-handling
    weight: decisive
    reason: Repository tooling is mostly reading and rewriting text files.
  - criterion: dependency-isolation
    weight: minor
    reason: Tooling scripts here lean on the standard library.
---

# PP-001: New repository tooling should default to Python

## Thesis

**Thesis**: New command-line tooling in a repository that already uses Python
should be written in Python, not Node.js, unless a script needs a Node.js
library with no equivalent.

## Audience and Stakes

Maintainers choosing a runtime for a new tooling script. A second runtime in
a repository adds installation and upkeep for every contributor.

## Decision Criteria

| Criterion | Weight | Why |
|-----------|--------|-----|
| Text and file handling | Decisive | Repository tooling is mostly reading and rewriting text files. |
| Dependency isolation | Minor | Tooling scripts here lean on the standard library. |

## Argument

1. Both runtimes handle text and file work comparably on the cited
   assessment. [TA-001, Comparison]
2. A repository with one runtime has less to install and maintain than one
   with two. Author's judgment.
3. So the existing runtime wins unless a library requires the other. Author's
   judgment.

## Objections and Answers

| Objection | Answer | Evidence |
|-----------|--------|----------|
| The team already writes JavaScript | Familiarity favors Node.js for that team; the thesis assumes the repository's existing runtime is Python | Author's judgment |
| Distribution of a single script may differ | The assessment has no finding on distribution; the thesis does not rely on it | TA-001, Contradictions and Gaps |

## Recommendations

| Technology | Stance | Context | Conditions | Based on |
|------------|--------|---------|------------|----------|
| Python | Use with conditions (Proposed) | repository-tooling | The repository already uses Python and no script needs a Node.js-only library. | TA-001 |

## Limits of the Position

The paper does not claim Python is better in general.

| Condition | Option that wins | Evidence |
|-----------|------------------|----------|
| The repository's existing runtime is Node.js | Node.js | Author's judgment: argument step 2 favours whichever runtime is already there |
| A script needs a library that exists only for Node.js | Node.js | Author's judgment |

## Transition Path

Existing Node.js scripts stay as they are. The position covers new tooling
only, so nothing is rewritten.

## Evidence

| Reference | Kind | Revision | Used for |
|-----------|------|----------|----------|
| TA-001 | Technology assessment | example | Argument step 1 |

Reference

ActivityDiscover — Validate that an opportunity is worth pursuing before committing to a development cycle.
Default locationdocs/helix/00-discover/position-paper-PP-{number}-{subject}.md
RequiresNone
EnablesNone
InformsDecision Brief
Deliverable
Generation prompt
Show the full generation prompt
# Position Paper Generation Prompt

Argue one position for a named audience on cited evidence, with the strongest
objections answered and the limits stated.

## Storage Location

Store at: `docs/helix/00-discover/position-paper-PP-{number}-{subject}.md`,
or the path the flow's graph profile sets for this type (`locations:`).

## Purpose

Answers: **What do we think about this, why should the audience agree, and
what would make us wrong?** It takes a side. It is not tied to one client.

## Role Boundary

A [[technology-assessment]] reports findings and takes no side; the paper
argues from them and cites them by pinned revision. A [[decision-brief]]
recommends for one named context; the paper does not. A paper may inform a
brief; it never overrides a client's requirements or decisions. A
[[deliverable]] presents a paper to an audience; the paper is the source.

## Method

1. **State the thesis** as a claim a reader can reject.
2. **Name the audience and the stakes.**
3. **Build the argument** as ordered claims. Cite evidence for facts; label
   judgments as the author's.
4. **Find the strongest objections,** including any raised by the cited
   evidence, and answer each. An objection the evidence supports and the
   paper cannot answer belongs in Limits.
5. **State the limits:** what the paper does not claim, then a table of when
   the other option wins: the condition, the option that wins under it, and
   the evidence. A `conditional` stance's conditions each imply a row.
   A paper written before the table existed gains it at its next revision;
   the validator warns until then.
6. **Record stances as data** when the paper advises one per technology and
   context: a `recommendations:` front matter block, each entry with its
   stance (recommended, conditional, watch, avoid), rationale, the pinned
   assessments and criteria it rests on, `since` and `review_by` dates, and
   `approved_by` with `approved_on` once a named person approves; until then
   it is proposed. Run `assessment-tables.py --write` for the table.
7. **Record weights as data** when the paper weighs criteria: a `weights:`
   list, each entry a criterion id that a `supported_by` assessment has a
   finding for, a weight of `decisive`, `important`, or `minor`, and a
   one-line reason. A weight is the paper's judgement, so it is never
   written into an assessment or `criteria.yml`, and never as a number. The
   same command writes the Decision Criteria table.
8. **Add a Transition Path** only when the position displaces something
   already in use.
9. **Pin the evidence** before publishing.

## Writing for the reader

Plain words, the thesis first. Do not present opinion as evidence, and do not
drop a fact because it hurts the case. A figure appears only with its source.

## Inputs

- Technology assessments and briefs the argument rests on
- The audience and what they decide
Template
Show the template structure
---
ddx:
  id: PP-[number]
  type: position-paper
  authoring:
    home: repo
  links:
    # - {id: <technology assessment id>, kind: supported_by, rev: <pinned revision>}
    # - {id: <technology brief id>, kind: supported_by, rev: <pinned revision>}
    # - {id: <other paper or assessment id>, kind: contradicts}
# Optional: stances as data. The Recommendations table below is then generated from it
# (`assessment-tables.py --write`).
# recommendations:
#   - subject: <technology brief id>
#     context: <the context the stance is for>
#     stance: recommended | conditional | watch | avoid
#     conditions: <required for conditional>
#     rationale: <why, in a sentence or two>
#     based_on: [{assessment: <assessment id>, criteria: [<criterion id>]}]
#     since: <date>
#     review_by: <date after since>
#     approved_by: <name>   # with approved_on, or neither: until then the stance is proposed
#     approved_on: <date>
# Optional: how much each criterion counts, as data. The Decision Criteria table below is then
# generated from it. A weight is the paper's judgement; an assessment and criteria.yml carry none.
# weights:
#   - criterion: <criterion id that a supported_by assessment has a finding for>
#     weight: decisive | important | minor
#     reason: <why it counts this much, in one line>
---

# PP-[number]: [The position as a claim]

## Thesis

**Thesis**: [The position in one or two sentences, as a claim a reader can
disagree with.]

## Audience and Stakes

Who the paper is for and what they decide or do differently if persuaded.
Name the audience by role, and say what is at stake for them.

## Decision Criteria

Only when the paper weighs the criteria its assessments rate. The table is
generated from `weights:`. A weight is decisive, important, or minor, never
a number, and it is the author's judgement: the reason says why.

| Criterion | Weight | Why |
|-----------|--------|-----|
| [Criterion] | [Decisive, Important, or Minor] | [Reason] |

## Argument

The case in order, each step a claim with its support. Label a claim of
judgment as the author's judgment; cite evidence for a claim of fact.

1. [Claim]. [Evidence, pinned revision, or "Author's judgment"]
2. [Claim]. [Evidence or "Author's judgment"]

## Objections and Answers

The strongest objections, including any the cited evidence raises.

| Objection | Answer | Evidence |
|-----------|--------|----------|
| [Objection] | [Answer] | [Source or "Author's judgment"] |

## Recommendations

Only when the paper advises a stance per technology and context. The table
is generated from `recommendations:`; the argument above is the case for it.

| Technology | Stance | Context | Conditions | Based on |
|------------|--------|---------|------------|----------|
| [Technology] | [Stance (Proposed or Approved)] | [Context] | [Conditions] | [Assessment id] |

## Limits of the Position

What the paper does not claim, in a sentence or two. Then when the other
option wins: one row per condition under which the thesis does not hold,
the option that wins under it, and the evidence (a pinned assessment's
rating, or "Author's judgment").

| Condition | Option that wins | Evidence |
|-----------|------------------|----------|
| [Condition] | [Option] | [Assessment id and criterion, or "Author's judgment"] |

## Transition Path

Optional: only when the position displaces something already in use. What
a team with the existing option does first, what can stay as it is, and
what would stop the move. Leave the section out when there is no incumbent.

## Evidence

| Reference | Kind | Revision | Used for |
|-----------|------|----------|----------|
| [Assessment, brief, or source] | [kind] | [revision or digest] | [claim] |
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/discover/position-paper.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:5c485753…620958d2

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/discover/position-paper/",
        "digest": {
          "alg": "sha256",
          "value": "5c48575324c0eba75a5e9b61386dc49d1b55a75f7226a22ac3236bde620958d2"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "Oc_zeRoL2ymxdOcOgQSkXm1h6llDUVJlAZJclZFbE5wUQdET1zu9EtQsXxXi1b0a0O7enWXfwwkEczmg9Z-mDg",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}