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 118 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

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.