Skip to content

Technology Assessment

Purpose

Answers: How do these technologies compare on these criteria, on the evidence we hold? It is reusable: no project, client, or deployment context appears in it.

Example

Show a worked example of this artifact
---
ddx:
  id: TA-001
  type: technology-assessment
  authoring:
    home: repo
  links:
    - {id: component-profile-nodejs-reusable, kind: evaluates, rev: example}
    - {id: component-profile-python-reusable, kind: evaluates, rev: example}
assessment:
  criteria: [script-distribution, text-and-file-handling, dependency-isolation]
  subjects:
    - {id: component-profile-nodejs-reusable, label: Node.js}
    - {id: component-profile-python-reusable, label: Python}
  ratings:
    - {criterion: script-distribution, subject: component-profile-nodejs-reusable, gap: Unknown (not in the brief)}
    - {criterion: script-distribution, subject: component-profile-python-reusable, gap: Unknown (not in the brief)}
    - {criterion: text-and-file-handling, subject: component-profile-nodejs-reusable, finding: Brief section Capabilities}
    - {criterion: text-and-file-handling, subject: component-profile-python-reusable, finding: Brief section Capabilities}
    - {criterion: dependency-isolation, subject: component-profile-nodejs-reusable, finding: Brief section Technology and Operations}
    - {criterion: dependency-isolation, subject: component-profile-python-reusable, finding: Brief section Technology and Operations}
---

# TA-001: Node.js and Python for command-line tooling

## Scope

Compares Node.js and Python as runtimes for repository tooling scripts: file
and text handling, packaging, and distribution of a single script. Excludes
web services and data science workloads.

## Criteria

| Criterion | Definition | Concern |
|-----------|------------|---------|
| Script distribution | How a single script is run on a machine that lacks the runtime's packages | none |
| Text and file handling | Standard-library support for reading, parsing, and writing text files | none |
| Dependency isolation | How a script declares and isolates its own dependencies | none |

## Technologies

- **Node.js**: a JavaScript runtime. Brief: component-profile-nodejs-reusable
- **Python**: a general-purpose language runtime. Brief: component-profile-python-reusable

## Comparison

| Criterion | Node.js | Python |
|-----------|---------|--------|
| Script distribution | Unknown (not in the brief) | Unknown (not in the brief) |
| Text and file handling | Brief section Capabilities | Brief section Capabilities |
| Dependency isolation | Brief section Technology and Operations | Brief section Technology and Operations |

## Findings

On the cited briefs the technologies are comparable for text and file
handling. Script distribution is not covered by either brief, so no finding is
made.

## Contradictions and Gaps

| Item | Sources or gap | Route |
|------|----------------|-------|
| Neither brief covers single-script distribution | Both briefs | Extend each brief, then re-read this criterion |

## Evidence

| Reference | Kind | Revision | Used for |
|-----------|------|----------|----------|
| component-profile-nodejs-reusable | Technology brief | example | Text handling, isolation |
| component-profile-python-reusable | Technology brief | example | Text handling, isolation |

Reference

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

Compare technologies on stated criteria from reusable technology briefs, and
state findings a later decision can rely on.

## Storage Location

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

## Purpose

Answers: **How do these technologies compare on these criteria, on the
evidence we hold?** It is reusable: no project, client, or deployment context
appears in it.

## Role Boundary

A [[component-profile]] with `scope: reusable` records one technology; the
assessment compares several and cites each brief by pinned revision rather
than restating it. A [[decision-brief]] recommends for one context; the
assessment never does. A [[position-paper]] argues a stance; the assessment
reports, and gives no criterion a weight: how much each counts is the
paper's judgement. If a reader needs "so which one", the assessment ends and a
Decision Brief begins.

## Method

1. **State the scope** and the technologies, including the version lines.
2. **Define the criteria** before grading, from concerns where one applies.
3. **Read each brief.** Grade every technology on every criterion from a
   brief section; where no brief speaks, write Unknown.
4. **Compare** in one table, cells citing sources. To keep the ratings as
   data, put them in an `assessment:` front matter block (criteria ids from
   `criteria.yml` at the flow root, a one-line finding or a stated gap for every criterion
   and subject) and run `assessment-tables.py --write`; the Criteria and
   Comparison tables are generated from it.
5. **Write findings** only where criteria separate the technologies.
6. **Record disagreement.** When two sources conflict, cite both, link with
   `contradicts`, and leave the conflict open until new evidence settles it.
7. **Pin the briefs** before publishing.

## Writing for the reviewer

Findings are claims with citations after them. Do not rank, score, or
recommend. A tie or an unknown is a finding.

## Inputs

- Reusable technology briefs for each technology
- Concerns that define criteria

## An assessment of a practice

Set `ddx.scope: practice` when the subject is a practice that no technology
assessment covers. Rate nothing: there are no criteria, subjects, or ratings,
and no Criteria, Technologies, Comparison, or Evidence section. Write Scope,
then Findings grouped by reader, then Contradictions and Gaps, then numbered
Sources cited at the clause. Say how each claimed benefit is supported: by
argument, by reported use, or by a named study. Where a technology assessment
already covers the subject, put the explanation of the practice at the front
of that assessment and write no second document.
Template
Show the template structure
---
ddx:
  id: TA-[number]
  type: technology-assessment
  authoring:
    home: repo
  links:
    # - {id: <technology brief id>, kind: evaluates, rev: <pinned revision>}
    # - {id: <source id>, kind: supported_by, rev: <pinned revision>}
    # - {id: <other assessment id>, kind: contradicts}
  # Optional: criteria and ratings as data. The Criteria and Comparison tables below are then
  # generated from it (`assessment-tables.py --write`) and cannot drift from it. Criteria are
  # ids from `criteria.yml` at the flow root (entries: id, label, definition, concern). A
  # `keys.yml` beside it may map short names to document ids; subjects and ratings accept a
  # key, while `ddx.links` keep the full id and pinned rev. The document records what each key
  # resolved to in a top-level `keys: {<key>: <document id>}`, so repointing a key in keys.yml
  # shows up as a finding here instead of silently changing what the assessment cites.
# assessment:
#   criteria: [<criterion id from the graph's criteria.yml>]
#   subjects: [{id: <technology brief id or a key from keys.yml>, label: <name in the table>}]
#   ratings:
#     - {criterion: <id>, subject: <brief id>, finding: "<finding, source>"}
#     - {criterion: <id>, subject: <brief id>, gap: Not published}
---

# TA-[number]: [Subject: what is compared]

**Scope kinds** (`ddx.scope`). Unset is this whole template: technologies
compared on criteria. `practice` is an assessment of a practice that no
technology assessment covers: write Scope, Findings, Contradictions and Gaps,
and Sources, and omit the `assessment:` block, Criteria, Technologies,
Comparison, and Evidence. Group its Findings by reader (cost and commitment,
security and compliance, running it, building on it). It names a product
only as an example of a kind of tool.

## Scope

What is compared and what is not. Name each technology and version line,
the kind of use the comparison speaks to, and what is excluded.

## Criteria

Each criterion, defined, with the concern it comes from when one applies.

| Criterion | Definition | Concern |
|-----------|------------|---------|
| [Criterion] | [What is measured or checked] | [Concern id, or none] |

## Technologies

One line each, with the technology brief it rests on.

- **[Technology A]**: [what it is]. Brief: [id, pinned revision]
- **[Technology B]**: [what it is]. Brief: [id, pinned revision]

## Comparison

Every technology on every criterion. Each cell cites a brief section or says
Unknown.

| Criterion | [Technology A] | [Technology B] |
|-----------|----------------|----------------|
| [Criterion] | [Finding, source] | [Finding, source] |

## Findings

What the comparison shows, one short paragraph per criterion that
separates the technologies. No recommendation for a project.

## Contradictions and Gaps

Where sources disagree (both cited), and what no brief covers.

| Item | Sources or gap | Route |
|------|----------------|-------|
| [Conflict or gap] | [Sources] | [Research, spike, or accepted] |

## Evidence

| Reference | Kind | Revision | Used for |
|-----------|------|----------|----------|
| [Technology brief or source] | [kind] | [revision or digest] | [criterion] |

## Sources

Practice scope only; an assessment of technologies cites its briefs under
Evidence. Number each source and cite it at the clause it supports.

1. [Title](https://example.org/public-page), [author or organization], [date on the page]. Read [date].
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/technology-assessment.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:b9c0ae61…daa90a77

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/technology-assessment/",
        "digest": {
          "alg": "sha256",
          "value": "b9c0ae61c50840fd2763b02219a6a28d6986d4a32458686182a1f320daa90a77"
        }
      }
    ],
    "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": "d-73MDs6Au_RaOfEfjiDb5KLxQqwMWCR7Vh0nT55R2zvuwAgEalph5FV_acdeN4AR_6Dt5ulaNWtDv_J5dn1DA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}