pragmaBit/ SDD GeneratorInitial package · DraftLet’s talk

PROJECT PREPARATION

From idea to documents.

Define your project, describe its requirements and complete each document’s questions.

01

Your project

These details are shared across all documents.

Summarize the change you want to develop. Choose a title that explains its purpose.

Example: Automate daily server backups

Name the application or tool. Its name also determines the package folder.

Example: Internal backups

Use three digits from 001 to 999. Choose an unused number in the destination repository.

Example: 007

Choose Public, Internal, Confidential or Restricted according to your organization’s policy and the data processed.

Example: Internal: operational documentation for the team

Enter the date you prepare the draft. This is not an approval date.

Example: 2026-10-05

02

What must the system do?

Each requirement will have an ID, acceptance criteria and initial tasks.

RF-001

Describe one function with a short name. Each requirement should be independently verifiable.

Example: Create a scheduled backup

Complete “The system must…” with an action and an observable result. Put technical design in the plan.

Example: create a nightly backup of the selected directories

Use Given / when / then: initial situation, action and expected successful result.

Example: Given an accessible source, when the scheduled time arrives, then a backup is created and its location reported

Use Given / when / then for invalid input or failure. State the expected error and what must be prevented.

Example: Given a missing source, when the backup runs, then an error is reported and no partial output is created

Must: essential; Should: important; Could: desirable; Wont: excluded from this delivery. Choose according to agreed scope.

Example: Must: creating backups is essential to the system’s purpose

03

Complete the documents

Optional fields. You can enter “Not applicable” with a justification.

0 of 189 questions answered
Specification30 questions

General information

Identify the business area and contact requesting the change.

Example: Operations / infrastructure owner

Name the person or role coordinating the technical work.

Example: Infrastructure lead / to be assigned

1. Context and problem

Describe the current process, who is affected and why it needs to change. Avoid technical solutions.

Example: Manual backups are sometimes missed; Operations cannot confirm their results

2. Goals and exclusions

State an observable result with a quantity or deadline where possible.

Example: Back up 10 servers nightly and record each result

State what this delivery explicitly excludes.

Example: No external cloud copies or database backups

3. Actors

Name a user, role or process interacting with the system.

Example: Infrastructure operator

Explain what the actor does and why they need the system.

Example: Configures directories and reviews daily backup results

State the actor’s role or permission; omit account credentials.

Example: backups.operator

5. Nonfunctional requirements

Describe the operation whose performance will be measured.

Example: Retrieve the latest backup result

Specify a measurable limit and test load. p95 means 95 % of responses meet the limit.

Example: p95 below 1 second with 10 concurrent users

Specify days, hours and time zone when the service must be available.

Example: Weekdays 08:00–20:00, Mexico City time

State the required availability and measurement period agreed with business.

Example: 99 % availability within the monthly service window

List supported platforms or clients, including operating systems for scripts.

Example: Windows with PowerShell 7 and Rocky Linux with Bash

Specify versions or a testable compatibility policy.

Example: PowerShell 7.4+ and Bash 5.x; tested on Windows 11 and Rocky Linux

6. Security requirements (A.8.26)

Specify the permission enforced by the server for this protected operation.

Example: backups.operator

Name the function controlled by the permission above.

Example: Configure and run backups

Describe checks the server or script must perform before processing input.

Example: Existing source directories, authorized destinations and HH:MM schedules only

State which personal data is processed and how it is minimized, protected and removed. Justify N/A.

Example: No personal data collected; logs contain server IDs and backup status only

7. Data

Name a relevant logical dataset.

Example: Backup execution

List the data fields without actual sensitive values.

Example: ID, server, start time, end time, status and size

Apply your organization’s information classification policy to this entity.

Example: Internal

State how long the entity is retained and what happens on expiry.

Example: 90 days, then deleted according to retention policy

Explain who or what produces these records.

Example: Scheduled backup process upon completion

8. External interfaces

Name the integration partner or justify N/A.

Example: Internal storage server

Specify whether the system receives data, sends data or both.

Example: Output: send the backup archive

Specify the transfer channel and data format.

Example: SFTP / tar.gz archive and JSON manifest

Describe the authentication mechanism without secret values.

Example: SSH key for an Operations-managed service account

9. Edge cases and errors

Describe an exceptional condition and its expected behavior.

Example: If storage is full, cancel the copy and keep the last valid backup

10. Open questions

State an unresolved decision and its impact.

Example: How many backups per server should be retained? This affects storage capacity

Name the role responsible for resolving this question and its due date if known.

Example: Infrastructure owner / due date pending

Technical plan34 questions

2. Technical approach

Summarize components and the main flow implementing the specification.

Example: A script reads configuration, validates paths, creates an archive and logs the result

List your project’s languages, runtimes and versions. The template stack is illustrative.

Example: Bash 5.x on Linux and PowerShell 7.4 on Windows

Explain any difference from the reference constitution and the exception to review.

Example: Scripts run locally through the operating system scheduler

3. Architecture

Identify what starts the process, even if there is no browser.

Example: Operator / task scheduler

Name the front server or explain direct execution if none exists.

Example: N/A: local script execution

Name the component executing the application logic.

Example: backup.ps1 or backup.sh

Describe database or file storage used by the solution.

Example: JSON configuration files and text logs

Name a new or modified component.

Example: Path validator

Describe this component’s job and boundaries.

Example: Verify that the source exists and destination is authorized

4. Data model

Describe tables, indexes and migrations, or file structures if there is no database.

Example: No database: configuration.json stores source, destination and schedule

Explain changes to existing data and any required downtime.

Example: None: the first deployment creates a new configuration folder

5. Interfaces

Specify the route or justify N/A if there is no HTTP interface.

Example: N/A: command-line tool

Describe accepted request structure or justify N/A.

Example: JSON object with source, destination and schedule

Describe returned data and errors or justify N/A.

Example: JSON containing execution ID and status

Specify the role required for this endpoint.

Example: backups.operator

Describe queues, files or scheduled tasks.

Example: Nightly scheduler reading a JSON configuration file

6. Dependencies

Name a dependency and complete version, license and justification in the plan.

Example: None beyond standard operating system utilities

7. Security

Describe how user or process identity is checked.

Example: Operating system service account

Define roles and where access is checked.

Example: Filesystem permissions validated before each backup

State where input is checked and output safely encoded.

Example: Validate paths before execution; structured JSON serialization

Describe where runtime secrets are supplied without revealing values.

Example: Restricted file outside the repository

List logged events, format and destination.

Example: JSON log: start, completion and error; local protected directory

8. Test strategy

Choose a tool for verifying isolated service logic.

Example: Bash test runner and PowerShell assertions

Describe the isolated environment for dependencies and migrations.

Example: Temporary directories with synthetic files

Describe how CA-* criteria are executed and verified.

Example: Script comparing restored file checksums

Explain how RS-* requirements will be tested.

Example: Permission tests, input validation tests and security checklist review

State whether data is synthetic or masked under an approved procedure.

Example: Synthetic files with no real personal data

9. Deployment and rollback

Name the installable package and version format.

Example: backups-1.0.0.zip

Summarize installation actions in execution order.

Example: Copy the validated package, set permissions, enable scheduled task

Describe how to restore the previous version and recover data.

Example: Disable new task and restore the prior script and configuration

State whether a window is needed and its expected duration.

Example: Required: 30 minutes outside backup hours

10. Technical risks

Describe a concrete technical failure and its consequences.

Example: Storage fills before the nightly backup completes

State how this risk will be reduced or detected.

Example: Check free space before copying and alert Operations

11. Related ADRs

Reference a proposed architecture decision by ID and title.

Example: ADR-001 — JSON configuration storage

Risk analysis20 questions

General information

List components, data and services affected by the change.

Example: File server, backup repository and scheduled task configuration

Specify the highest classification under your policy; the template value is illustrative.

Example: Internal

Answer Yes or No and explain any Internet-facing component.

Example: No: processing and storage remain on the internal network

Answer Yes or No and explain any personal data involved.

Example: No: test files and logs contain technical information only

List categories or justify N/A.

Example: N/A: no personal data is collected

State whether a third party develops, operates or stores any part.

Example: No: the internal team develops and operates the tool

Threats and treatment

Describe an event affecting confidentiality, integrity or availability.

Example: An unauthorized account deletes backups

Describe the weakness allowing the threat to materialize.

Example: Execution account can delete all copies

Rate likelihood using your organization’s scale and explain the evidence.

Example: 3: possible within a year based on service history

Rate impact using your organization’s scale and identify affected services or data.

Example: 4: several servers would lose file recovery capability

Rate risk before controls using your methodology; show the calculation.

Example: P=3 and I=4; initial risk 12 on a 1–5 matrix

Specify mitigation, avoidance, transfer or acceptance and its owner.

Example: Mitigate: separate copying and deletion accounts; owner Operations

Reference the RS requirement or control implementing treatment.

Example: RS-001: restrict deletion to authorized users

Rate remaining risk after controls without declaring it approved.

Example: P=1 and I=4; residual 4, pending review

Rate this threat’s likelihood using your organization’s scale and evidence.

Example: 3: possible based on prior access incidents

Rate the impact and explain which services or data would be affected.

Example: 4: loss of backup recovery for multiple servers

Describe another relevant threat or justify N/A.

Example: Destination storage fills and stops receiving copies

Conclusion

State the highest residual rating and its scale.

Example: 4 on the team’s likelihood × impact scale

Compare residual risk with your organization’s threshold, or leave assessment pending.

Example: Pending assessment by the service owner

Name the role responsible for acceptance or escalation.

Example: Infrastructure service owner

Architecture decision8 questions

General information

Summarize the proposed technical choice.

Example: Use JSON files for configuration

Name participants who will review the proposal; this does not imply approval.

Example: Technical lead and Operations representative

Context

Explain the problem, constraints and requirements motivating the choice.

Example: Tool must run without a database server; configuration changes infrequently

Decision

State the proposed choice and its scope in active voice.

Example: Store configuration in a JSON file with restricted permissions

Alternatives considered

Name another option and its benefits or drawbacks.

Example: SQLite supports queries but adds a storage format

Consequences

Describe concrete benefits of this choice.

Example: No additional service to administer

Describe costs, limitations or debt created by this choice.

Example: Concurrent editing requires explicit coordination

Explain effects on permissions, data protection, logging or reviews.

Example: Execution account reads configuration only; changes are reviewed in git

Security review2 questions

General information

Provide the pull request URL, or leave pending if it does not yet exist.

Example: https://git.internal.example/team/backups/pulls/12

Name the reviewer, separate from the author when required.

Example: Infrastructure reviewer / to be assigned

Production deployment1 question

General information

Enter the assigned change ID or leave it pending.

Example: 2026-007

Change request15 questions

General information

Use the identifier defined by your change management procedure.

Example: 2026-007

Choose Standard, Normal or Emergency according to your procedure and justify it.

Example: Normal: new scheduled process requiring prior review

Identify the exact name, version and actual checksum when available.

Example: backups-1.0.0.zip; checksum pending package build

Name who requests the production deployment.

Example: Operations owner / to be assigned

Name who will execute the change in the target environment.

Example: Operations engineer / to be assigned

Specify date, start/end times and time zone.

Example: 2026-10-15 22:00–23:00, Mexico City time

Describe expected service effects and interruption duration.

Example: No outage: enable the task after the current copy completes

Description

Summarize the installed version and resulting user behavior.

Example: Install automatic daily backups; Operations reviews results in a log

Prerequisites

Provide the actual commit that passed the pipeline; leave pending if untested.

Example: Pending: record the approved commit before deployment

State its location and how recoverability will be checked.

Example: Internal backup repository; test restoration pending

Execution steps

Describe one ordered deployment action and its executor.

Example: Operations disables the task, copies the validated package and checks permissions

Post-deployment verification

Specify a short check proving the service works after deployment.

Example: Back up a test file and verify its checksum

Rollback

Define an observable trigger and who decides to roll back.

Example: If the first test copy fails, Operations restores the previous version

Describe an action that restores the previous version.

Example: Disable the new task and restore the prior script

Closure

Describe information to record on closure; do not claim results that do not yet exist.

Example: Pending execution: record end time, test outcome and incidents

Change review2 questions

What

Describe the problem solved and resulting behavior for the reviewer.

Example: Automates nightly copying and reports unavailable source directories

How to test

Explain how to reproduce tests and what the reviewer should observe.

Example: Run tests with synthetic data; invalid sources produce no output

Legacy system inventory30 questions

General information

Use the name recognized by business users.

Example: Internal backup manager

Name the area using and owning the application.

Example: Infrastructure Operations

Name the maintainer or explicitly state that none is identified.

Example: Infrastructure team; individual owner to be assigned

Apply your organization’s information classification policy.

Example: Internal

Estimate how many internal users currently use the system.

Example: 8

Estimate how many external users currently use the system.

Example: 0

State days, times and time zone of actual use.

Example: Weekdays 08:00–18:00, Mexico City time

State when use began and the source of the estimate.

Example: 2018, according to available records

Technology

Record the OS and version observed in the existing environment.

Example: Rocky Linux 8.x

Record server/version or justify N/A.

Example: N/A: scripts run through cron

Record current languages and runtime versions.

Example: Bash 4.x and PowerShell 5.1

Record the application server/version or explain why none is used.

Example: N/A: no application server

Record database/version or file storage.

Example: No database: configuration files and logs

List observed frameworks or libraries and versions.

Example: No frameworks; scripts invoke operating system utilities

Current deployment

Associate inventory names with their function, omitting sensitive addresses.

Example: backup-01: executor; storage-01: copy destination

List deployed files, scripts and schedules.

Example: /opt/backups/bin, /etc/backups and daily cron task

Describe location and custodians without copying secret values.

Example: SSH key managed by Operations outside git

Describe the actual process, including manual steps.

Example: Operations copies scripts and updates the scheduled task

Dependencies

Name the logical schema or justify N/A.

Example: N/A: file storage

List tables read or modified by other systems.

Example: N/A: no shared database

Identify the scheduled task the application depends on.

Example: Run /opt/backups/bin/daily.sh

State frequency, time and time zone.

Example: Daily at 02:00, Mexico City time

State the resource and protocol without credentials.

Example: Backup folder mounted through NFS

Code metrics

Give measured counts and explain the scope or method.

Example: Bash: 900 lines; PowerShell: 600 lines in the reviewed repository

State how many source files were counted and the measurement scope.

Example: 25 source files in the reviewed repository

State the count and scope of detected embedded SQL locations.

Example: 2 locations detected; pending review

State the count and scope of possible secret locations without values.

Example: 2 locations detected; immediate treatment pending

Known risks

Describe observed risks and impact without assuming unverified conditions.

Example: No documented restoration tests for current backups

Disposition assessment (6R)

State the chosen preliminary system strategy.

Example: Refactor: preserve function and improve error validation

Justify the strategy with needs, constraints and risks.

Example: Preserve working behavior while correcting silent failures

Current behavior17 questions

General information

Identify the part of the existing system being documented.

Example: Nightly backup

1. Observed purpose

Describe actual use based on interviews and observation.

Example: Operations keeps a daily copy to recover deleted files

2. Observed functions

Name a function actually observed in the current system.

Example: Copy directories to the nightly folder

Identify the screen, request or scheduled task initiating it.

Example: Daily cron task at 02:00

Describe real accepted data and formats, including unexpected cases.

Example: Text file with one absolute path per line

Describe existing rules even if they need correction later.

Example: Skips missing paths and continues without returning an error

List the effects produced by the function today.

Example: Creates tar.gz archive and appends a log line

Reference reviewed code, a test or an observation supporting the description.

Example: bin/daily.sh:30–65; CAR-001 nightly copy test

Describe existing defects and user workarounds.

Example: Log reports success when a path was skipped; Operations checks manually

3. Implicit business rules

Explain a rule applied by code even if undocumented.

Example: Keep only the latest archive per server

Identify where the rule is implemented and how you found it.

Example: bin/daily.sh, old-file cleanup section

4. Actual data model

Describe discovered structures and meanings without correcting them yet.

Example: CSV with server, date and status; value 9 means copy failure

5. Actual interfaces

Describe present input/output, including direct access by other systems.

Example: Reads source paths from TXT and writes copies to NFS

6. Observed security

Describe identity checks; explicitly state if none exist.

Example: Operating system service account

Describe parameterized or concatenated SQL and reviewed evidence, or justify N/A.

Example: N/A: no database

Describe storage and access without copying secrets.

Example: File outside git readable by the service account

Describe events, storage and observed omissions.

Example: Daily start/result log; skipped paths are not recorded

Characterization tests4 questions

General information

Provide the file path used to reproduce current behavior.

Example: caracterizacion/create-customer.request.txt

Provide the captured and reviewed current output path.

Example: caracterizacion/create-customer.response.golden

Provide the script preparing synthetic characterization data.

Example: caracterizacion/prepare-data.sql

Provide the expected data path used for comparison.

Example: caracterizacion/customers.golden.csv

Migration plan20 questions

General information

Choose and justify Rehost, Replatform, Refactor, Replace or Retire.

Example: Replatform: preserve functions and move execution to the target

Choose complete cutover, gradual replacement or parallel comparison.

Example: Parallel execution for two weeks to compare results

State the planned completion date or leave pending if not agreed.

Example: 2026-11-15, pending Operations agreement

1. Source and target state

Record the current OS and verified version.

Example: Rocky Linux 8.x

State the planned version; compatibility validation belongs in the plan.

Example: 10.x, subject to testing

Record the runtime/version found on the source.

Example: PowerShell 5.1

State planned runtimes and versions.

Example: PowerShell 7.4 and Bash 5.x

Record the server/version or explain why none exists.

Example: N/A: scripts execute directly

State the planned version or justify N/A for another runtime.

Example: N/A: scripts without an application server

Record database/version or justify N/A.

Example: N/A: configuration files only

State the planned version or describe alternative target storage.

Example: N/A: JSON files

2. Phases

Identify the first module and behaviors to preserve.

Example: Daily scheduling; AS-001 and RF-001

Identify another module and dependencies on the first.

Example: File restoration; RF-002

4. Data

Describe data transfer and synchronization during coexistence.

Example: Copy configuration and verify checksums before enabling tasks

Define how equivalent source/target data will be confirmed.

Example: Compare file counts, sizes and checksums for each backup

List data excluded from migration and its archival or deletion policy.

Example: Logs older than retention period archived before cutover

5. Cutover

Describe an action, owner, duration and verification.

Example: Operations disables the old task and checks no copy is still running

6. Rollback

Define a measurable condition requiring a return to source.

Example: If checksum comparison fails, disable target and restore the old task

State when direct rollback becomes unsafe and what recovery is needed.

Example: After source data deletion; recovery requires a verified backup

7. Risks

Describe a specific migration risk and how it will be detected or reduced.

Example: Lost file permissions: compare source/target permissions before cutover

Evidence retention6 questions

General information

State years retained after system retirement according to your policy.

Example: 5 additional years, subject to organizational retention policy

Specify the approved retention period; the template number is illustrative.

Example: 12 months, if required by internal policy

Specify the applicable retention period for this evidence.

Example: 3 years; confirm with the ISMS owner

Specify the applicable retention period for this evidence.

Example: 3 years; confirm with the ISMS owner

Specify the applicable retention period for this evidence.

Example: 3 years; confirm with the ISMS owner

Specify the applicable retention period for this evidence.

Example: 3 years; confirm with the ISMS owner

Your package, ready for review

Includes the constitution, documents, tasks and ISMS controls.
Approvals and tests remain pending review.

Answers are not stored on the server. Save the JSON to continue later.