SOCK task guides

Add a source#

1. 01

   Confirm authorisation

   Verify that the source, its data classification, and its AI processing path are approved for this harness.

2. 02

   Choose the correct tab

   Local Repositories for a repository or folder, Knowledge Artifacts for documents, Connect System for an approved read-only PostgreSQL, MongoDB, or Oracle connection, Add Tacit Knowledge for attributed human knowledge.

3. 03

   Select the narrowest useful scope

   Choose an exact repository revision, approved folder, database or schema scope, space, or bounded knowledge note.

4. 04

   Record intentional omissions

   Name unavailable or excluded sources so the boundary stays honest.

5. 05

   Review before locking

   Confirm every source is correct. You cannot change the set after you lock the list.

Connect a supported database#

The connector families available today are PostgreSQL, MongoDB, and Oracle. Jira and GitLab are workflow integrations outside SOCK; Confluence has no supported user entry point. See connectors and integrations.

1. 01

   Check the version floor

   PostgreSQL must be 15 or later, MongoDB 7 or later, and Oracle 19 or later. A below-floor server is refused before any harness files are written.

2. 02

   Check the driver

   MSOCK reports whether the database driver this connector needs is available on your computer, and tells you what to install if it is not.

3. 03

   Prepare a least-privilege account

   Grant read-only access to only the database objects approved for the harness.

4. 04

   Connect and verify

   Provide the deployment-specific connection details, choose the TLS or SSL mode your server requires, and test access. After authorisation the secret is held in your operating system's secure credential store. Confirm TLS, VPN, proxy, and allow-list requirements.

5. 05

   Browse and select scope

   Choose the database, schemas, tables, collections, or objects that belong in the declared boundary.

6. 06

   Decide on sampling

   Sample rows may contain sensitive data. Disable sampling or constrain it to the authorised size when required.

7. 07

   Add the database to Sources

   Confirm the selected objects and permitted samples appear alongside repositories, documents, and tacit notes before you lock the list.

Add tacit knowledge#

1. 01

   Choose Add Tacit Knowledge

   Use this tab when important context is not present in repositories, documents, or connected systems.

2. 02

   Give the note a useful title

   Name the decision, operating procedure, glossary, ownership boundary, or historical context being recorded.

3. 03

   Write in Markdown

   State who supplied the information, when it was current, which systems or environments it applies to, and what evidence could confirm it.

4. 04

   Preview before adding

   Check the note and remove secrets, personal data, and unsupported certainty.

5. 05

   Lock it with the source list

   The note becomes attributed, human-reported evidence inside the same permanent boundary.

Annotate a source before locking#

1. 01

   Add and prepare the source

   Wait until the source row shows that preparation or connection has completed.

2. 02

   Choose Note

   Add concise source-specific context such as purpose, owner, environment, branch intent, caveat, or expected blind spot.

3. 03

   Keep fact and interpretation separate

   Describe why the source matters without changing what it says. Use a tacit-knowledge source for longer standalone knowledge.

4. 04

   Review before locking

   Confirm the note contains no secret or unauthorised data and still applies to the selected revision or export.

Lock the source list#

• Repositories resolve to an exact commit and a locked archive is created.
• Files and folders are copied under guarded rules and content hashes are recorded.
• Supported databases are queried read-only and a bounded capture-time export is written.
• A source that cannot be locked records a failure reason; a silently empty harness is never accepted.
• Processing starts only after the boundary is durable.

Scan the sources#

1. 01

   Confirm every source is locked

   Resolve any failed source before continuing; do not proceed with a silently missing one.

2. 02

   Start the scan

   Choose Start scan. SOCK probes the locked sources, records their structure and access boundary, and identifies what it can and cannot inspect.

3. 03

   Follow durable progress

   Use the task ledger, processed-source count, blockers, and run activity to judge progress. The live terminal explains the session but is not the completion record.

4. 04

   Review the source descriptions

   Check that each locked source is described accurately and that unavailable evidence, access limits, and other gaps remain visible.

5. 05

   Let the order analysis finish

   The same tab then analyses the extraction order. If it shows Finishing the order…, allow it to settle rather than starting a second run.

Approve the extraction order and extract#

1. 01

   Open the Extract tab

   The proposed order is reviewed here, not on a separate Plan stage.

2. 02

   Review scope and dependencies

   Check that the order covers the intended repositories, documents, and connected systems without implying access beyond the locked boundary.

3. 03

   Approve the order

   Choose Approve the order. If the approval appears to stall, use Re-check now rather than starting a duplicate run.

4. 04

   Extract

   Choose Extract all to run the whole queue. SOCK writes facts, citations, evidence tiers, Known Unknowns, and generated knowledge files to disk.

5. 05

   Watch tasks, blockers, and knowledge health

   Use durable task counts and the knowledge-health panel to see facts, inferred output, and recorded gaps as completed tasks land.

6. 06

   Review a blocked task before resuming

   Read the persisted failure reason and preserve completed work. Resume from the last durable marker rather than restarting the harness.

Preview extracted knowledge and evidence#

1. 01

   Wait for a task to complete

   Use the extraction queue and durable task count, not terminal silence.

2. 02

   Choose Preview

   The viewer shows the generated artefact tree without changing the harness.

3. 03

   Read the README

   Start with the task summary and captured scope before reviewing individual dimension documents.

4. 04

   Inspect Evidence

   Check the statement, citation, tier, and status columns. Follow important citations back to the locked source.

5. 05

   Inspect Known Unknowns

   Treat missing evidence, unresolved references, and unsupported conclusions as part of the result rather than defects to hide.

The generated tree is designed for investigation, not only stage completion. Depending on the source, it can include API and event contracts, system-design and integration views, configuration, data structures, dependency findings, operational evidence, security observations, and dimension-specific knowledge. Start with the README and coverage report, then follow the artefact that answers your question.

Do not judge a generated artefact only by how complete its prose appears. Check whether its important claims lead to evidence, whether inference is labelled, and whether unresolved boundaries remain visible.

Run Synthesize#

Synthesize reads across completed extraction tasks to catalogue discovered items no single source shows, then derives deeper candidate knowledge from them. They are two passes behind one tab.

1. 01

   Confirm Extract is complete

   All required tasks should show durable completion. Review blocked tasks and known gaps first.

2. 02

   Open Synthesize

   Start or resume the stage and follow run activity through discovery and then inference.

3. 03

   Filter by lens

   Use Structure, Integration, Reliability, Security, Change & risk, or Other to narrow the review. All restores the complete list.

4. 04

   Review dimension coverage

   Expand dimensions and inspect item counts. Zero can be honest; it does not prove the concern is absent from the real estate.

5. 05

   Preview a discovered item

   Inspect its source evidence and cross-source context before accepting it as useful.

6. 06

   Check inference and knowledge health

   Confirm derived output stays marked as inferred, evidence-linked, and separate from verified facts. Review recorded gaps before continuing.

Use the reference glossary to understand the concern and review question behind every identifier.

Read across sources, not just down a list#

The value of Synthesize appears when a concern is split across units: one source declares an endpoint, another implements a downstream call, a third supplies configuration, and a fourth owns the receiving side. A discovered call chain, business journey, interface mapping, or reliability finding can connect those fragments while retaining the evidence for each part.

The 21 authored dimensions are the baseline readers supplied with SOCK; they are not a closed taxonomy for every result. The current product can preserve additional recognised kinds and place them under the appropriate lens or Other. Review the kinds and counts shown by the harness instead of assuming every run will stop at exactly 21 labels.

Ask a grounded question#

1. 01

   Open the harness

   Choose the harness whose locked boundary matches your question.

2. 02

   Open Review, then Ask

   Ask is the second tab of the Review destination and is always read-only.

3. 03

   Write a bounded question

   Prefer "Which configuration controls retry behaviour?" over "Explain everything about reliability."

4. 04

   Review scope and evidence

   Inspect citations and note whether the answer is an observation, an interpretation, or a Known Unknown.

5. 05

   Verify consequential claims

   Open the cited source before acting on security, architecture, data, or release decisions.

Use the terminal and run activity#

• The terminal is a live view of the session executing the active stage.
• Use it to inspect commands, active work, diagnostic output, and a pause that needs attention.
• Use run activity for durable stage events and transitions.
• Do not infer completion from a quiet prompt or a narrative line. Trust persisted artefacts, task counts, stage status, and completion markers.
• If scheduling stops, use the stage's resume action. Do not start a duplicate run because the terminal looks idle.

Resume an interrupted run#

1. 01

   Return to the harness

   Review the current durable processing state. The harness list shows Scan resumable when a scan stopped part-way.

2. 02

   Use the resume action

   Continue from the last completed marker rather than starting a duplicate run.

3. 03

   Allow Finishing… to settle

   This state appears while completion evidence is being committed. A quiet terminal is not proof of failure.

4. 04

   Read the blocker

   If processing cannot continue, use the persisted failure reason to correct access, credentials, data, or environment conditions.

5. 05

   Answer a pending question

   A harness can show Needs your answer when the run escalated a question. Answer it to let the run continue.

Delete a harness from this machine#

Deleting removes the working harness and its locked evidence from your machine. A version you have already published to your team is served from its own release and is unaffected by deleting the working copy — but a local-only release is not. Read the dialog before confirming.

Run a meaningful validation harness#

1. 01

   Agree the evidence boundary

   Name repositories and revisions, folders, documents, database scope, team notes, and intentionally omitted sources.

2. 02

   Agree the questions first

   Define what you need to learn and what an honest unsupported answer should look like.

3. 03

   Evaluate traceability

   Check locked provenance, citation reachability, visible Known Unknowns, resumability, and the distinction between candidates and verified relationships.

4. 04

   Measure outcomes, not volume

   Do not use fact count as the success metric. More facts can reflect source size or noise rather than better comprehension.